Problem Description

Currently, automated JSON formatting and linting are explicitly disabled in both CI Super-Linter (VALIDATE_JSON_PRETTIER: false, VALIDATE_BIOME_FORMAT: false in .github/workflows/linter.yaml) and local pre-commit hooks (Prettier is restricted via types: [css] in .pre-commit-config.yaml).

As a result, schema files across source/schemas/ have drifted into inconsistent styling across files (and even within the same PR), depending on whether they were authored by hand, edited by script, or generated.

Examples of Formatting Discrepancies Today

1. Compact vs. Multi-Line Conditionals:

   • In source/schemas/shopping/types/fulfillment_destination.json:

     {
       "if": {
         "properties": { "type": { "const": "shipping_address" } },
         "required": ["type"]
       },
       "then": {
         "": "shipping_destination.json"
       }
     }

   • In source/schemas/shopping/types/fulfillment_method.json:

     {
       "if": {
         "properties": {
           "type": {
             "const": "shipping"
           }
         },
         "required": [
           "type"
         ]
       }
     }

2. Single-Element and Short Arrays:

   • In source/schemas/shopping/types/location_destination.json: "required": ["type"], (compact single line)
   • In source/schemas/shopping/types/fulfillment_method.json:

     "required": [
       "type"
     ]

3. UCP Annotation Serialization:

   • In some files: "ucp_request": {"create": "omit", "update": "optional"}
   • In other files, the annotation object is split across 4 lines.

Steps Required to Maintain Git History (git blame)

A major concern with standardizing repository-wide JSON formatting is polluting git blame and losing historical line attribution for protocol design decisions.

To standardize without eroding git history:

1. Define the Canonical Formatter Config: Establish standard JSON formatting rules in .prettierrc (or Biome).
2. Execute in an Isolated Commit: Apply the formatter across all source/schemas/ and other .json files in a single, dedicated commit (e.g. style: standardize JSON formatting across repository).
3. Register in .git-blame-ignore-revs:
   • Create .git-blame-ignore-revs at the repository root and add the SHA of the formatting commit.
   • GitHub natively recognizes this file in the blame UI, ensuring historical author attributions remain visible.
   • Document git config blame.ignoreRevsFile .git-blame-ignore-revs in CONTRIBUTING.md for local git blame usage.
4. Enable Automated Enforcement:
   • Update .pre-commit-config.yaml to include JSON files in Prettier.
   • Update .github/workflows/linter.yaml to set VALIDATE_JSON_PRETTIER: true so future PRs remain consistent automatically.