◇ Open Values Standardfor builders

Spec / ovs-node-readiness

Open Values Node Readiness v0.1

A status report on the generated node and Ask search files: what the app loads and in what order, file sizes, and what must happen before each kind of page goes public. The data build writes it for the people wiring those files into the app. It is an internal file used while building the site.

Used while building the sites. Not meant for other apps. Data kept for tests, not for use.

Who writes it and who reads it

Written by pipeline/build_nodes.js. Read by app-lane integration, preview QA.

Fields

FieldWhat it meansType
format requiredNames this file's format, so a reader can check it before reading the rest of the file.always "ovs-node-readiness"
version requiredThe version of the format this file follows, such as "0.1".see version
built requiredThe date of the source data this file was built from, as YYYY-MM-DD.see date
source requiredThe script that wrote this file, or the files it was built from.see source
status requiredAlways "ready-for-app-integration": the generated files are complete and wait on the app.always "ready-for-app-integration"
appLaneNote requiredA note on which choices this file leaves to the app code that reads it, such as fetching, layout and wording.see nonEmptyString
runtimePlan requiredWhat the app loads while running, in order, and what each step is for.list
devContracts requiredFiles used only in testing and review, with what each is for.list
routeContract requiredThe route pattern for each kind of page, such as "#n/<type>/<slug>" for node pages.object
counts requiredCounts of generated nodes and Ask index entries, by name, such as "brands" or "askTokens".object
budgets requiredByte sizes and limits for loading, such as the size of ask-core.json and the startup limit.object
publicGates requiredThe conditions each kind of generated page must meet before it moves out of the private workbench and goes public.see publicGates
h4DrainContract requiredThe steps the app must show evidence for before handoff item H4 in docs/CONTENT-HANDOFF.md can be closed. H4 is the work of wiring the generated node and Ask files into the app.see h4DrainContract
goldenQueries requiredSample Ask queries with the results the startup index gives for each, as a quick check.list

A reader MUST ignore fields it does not know, so a file can carry more than this list and still be read. A writer MUST NOT change what a listed field means.

A file that passes

Node readiness reports runtime plans, dev contracts, route contracts, budgets, and golden queries.

{
  "format": "ovs-node-readiness",
  "version": "0.1",
  "built": "2026-07-07",
  "source": "pipeline/build_nodes.js",
  "status": "ready-for-app-integration",
  "appLaneNote": "Generated data only; app-owned code chooses loading.",
  "runtimePlan": [
    {
      "step": 1,
      "files": [
        "manifest.json"
      ],
      "purpose": "Load metadata."
    }
  ],
  "devContracts": [
    {
      "file": "ask-fixtures.json",
      "purpose": "Golden resolver cases."
    }
  ],
  "routeContract": {
    "category": "#explore/<cid>",
    "guide": "#guide/<slug>",
    "item": "#item/<cid>/<code>",
    "node": "#n/<type>/<slug>"
  },
  "counts": {
    "brands": 1
  },
  "budgets": {
    "startupBudgetBytes": 780000
  },
  "goldenQueries": [
    {
      "query": "best bank",
      "ok": true
    }
  ],
  "publicGates": {
    "status": "ready-for-app-public-gates",
    "namedConsumer": "App I5 workbench graduation",
    "voiceSource": "BUILD-PLAN.md#c8-voice-pass-status",
    "rule": "Move one surface public at a time after app-owned rendering consumes generated files.",
    "appOwnedBeforePublic": [
      "Render from generated data.",
      "Keep app-added copy in the signed voice."
    ],
    "releaseContract": {
      "purpose": "App-owned public release contract.",
      "status": "ready-for-app-public-gates",
      "namedConsumer": "App I5 workbench graduation",
      "releaseRule": "Release one surface at a time after app-owned evidence.",
      "voiceSource": "BUILD-PLAN.md#c8-voice-pass-status",
      "releaseOrder": [
        {
          "step": 1,
          "surfaceId": "company-pages",
          "label": "Company pages",
          "voiceStatus": "signed",
          "sourceFiles": [
            "app/data/nodes/companies.json",
            "BUILD-PLAN.md"
          ],
          "evidenceRequired": [
            "Rendering evidence."
          ],
          "releaseWhen": [
            "Gate passes."
          ],
          "mustNot": [
            "Do not overclaim coverage."
          ]
        }
      ],
      "sharedEvidenceRequired": [
        "Smoke commands pass."
      ],
      "rollbackRule": "Rollback only the failed surface.",
      "coverage": {
        "surfaces": 1,
        "releaseSteps": 1,
        "allSurfacesCovered": true,
        "minimalGeneratedCopy": [],
        "signedSurfaces": [
          "company-pages"
        ]
      }
    },
    "surfaces": [
      {
        "id": "company-pages",
        "label": "Company pages",
        "owner": "app/design",
        "status": "voice-signed-app-gate",
        "proseClass": "company-reads",
        "sourceFiles": [
          "app/data/nodes/companies.json",
          "BUILD-PLAN.md"
        ],
        "voice": {
          "status": "signed",
          "signedAt": "2026-07-08",
          "signoffBlock": "BUILD-PLAN.md#c8-voice-pass-status",
          "pilotSamples": 5
        },
        "generatedCount": 1,
        "appOwnedGate": "Render signed reads with receipts before public release.",
        "mustNot": [
          "Do not overclaim coverage."
        ]
      }
    ]
  },
  "h4DrainContract": {
    "purpose": "App-owned H4 drain contract.",
    "status": "pending-app-integration",
    "activeHandoff": "H4",
    "namedConsumer": "App H4 generated-node integration drain pass",
    "h4DrainableFromDataAlone": false,
    "drainRule": "H4 drains only after app-owned implementation evidence; generated data alone is insufficient.",
    "steps": [
      {
        "step": 1,
        "id": "startup-ask",
        "label": "Startup Ask",
        "phaseIds": [
          "startup-ask"
        ],
        "sourceFiles": [
          "ask-core.json"
        ],
        "contractPointer": "ask-core.json#startupContract",
        "appOwnedEvidence": [
          "Running app note."
        ],
        "passWhen": [
          "App behavior passes."
        ],
        "mustNot": [
          "Do not drain from data alone."
        ]
      }
    ],
    "finalDecision": {
      "expe
…

A file that must be rejected

Readiness files must not claim an arbitrary integration status.

{
  "format": "ovs-node-readiness",
  "version": "0.1",
  "built": "2026-07-07",
  "source": "pipeline/build_nodes.js",
  "status": "done",
  "appLaneNote": "Generated data only.",
  "runtimePlan": [
    {
      "step": 1,
      "files": [
        "manifest.json"
      ],
      "purpose": "Load metadata."
    }
  ],
  "devContracts": [
    {
      "file": "ask-fixtures.json",
      "purpose": "Golden resolver cases."
    }
  ],
  "routeContract": {
    "category": "#explore/<cid>",
    "guide": "#guide/<slug>",
    "item": "#item/<cid>/<code>",
    "node": "#n/<type>/<slug>"
  },
  "counts": {
    "brands": 1
  },
  "budgets": {
    "startupBudgetBytes": 780000
  },
  "goldenQueries": [
    {
      "query": "best bank"
    }
  ],
  "publicGates": {
    "status": "ready-for-app-public-gates",
    "namedConsumer": "App I5 workbench graduation",
    "voiceSource": "BUILD-PLAN.md#c8-voice-pass-status",
    "rule": "Move one surface public at a time after app-owned rendering consumes generated files.",
    "appOwnedBeforePublic": [
      "Render from generated data.",
      "Keep app-added copy in the signed voice."
    ],
    "releaseContract": {
      "purpose": "App-owned public release contract.",
      "status": "ready-for-app-public-gates",
      "namedConsumer": "App I5 workbench graduation",
      "releaseRule": "Release one surface at a time after app-owned evidence.",
      "voiceSource": "BUILD-PLAN.md#c8-voice-pass-status",
      "releaseOrder": [
        {
          "step": 1,
          "surfaceId": "company-pages",
          "label": "Company pages",
          "voiceStatus": "signed",
          "sourceFiles": [
            "app/data/nodes/companies.json",
            "BUILD-PLAN.md"
          ],
          "evidenceRequired": [
            "Rendering evidence."
          ],
          "releaseWhen": [
            "Gate passes."
          ],
          "mustNot": [
            "Do not overclaim coverage."
          ]
        }
      ],
      "sharedEvidenceRequired": [
        "Smoke commands pass."
      ],
      "rollbackRule": "Rollback only the failed surface.",
      "coverage": {
        "surfaces": 1,
        "releaseSteps": 1,
        "allSurfacesCovered": true,
        "minimalGeneratedCopy": [],
        "signedSurfaces": [
          "company-pages"
        ]
      }
    },
    "surfaces": [
      {
        "id": "company-pages",
        "label": "Company pages",
        "owner": "app/design",
        "status": "voice-signed-app-gate",
        "proseClass": "company-reads",
        "sourceFiles": [
          "app/data/nodes/companies.json",
          "BUILD-PLAN.md"
        ],
        "voice": {
          "status": "signed",
          "signedAt": "2026-07-08",
          "signoffBlock": "BUILD-PLAN.md#c8-voice-pass-status",
          "pilotSamples": 5
        },
        "generatedCount": 1,
        "appOwnedGate": "Render signed reads with receipts before public release.",
        "mustNot": [
          "Do not overclaim coverage."
        ]
      }
    ]
  },
  "h4DrainContract": {
    "purpose": "App-owned H4 drain contract.",
    "status": "pending-app-integration",
    "activeHandoff": "H4",
    "namedConsumer": "App H4 generated-node integration drain pass",
    "h4DrainableFromDataAlone": false,
    "drainRule": "H4 drains only after app-owned implementation evidence; generated data alone is insufficient.",
    "steps": [
      {
        "step": 1,
        "id": "startup-ask",
        "label": "Startup Ask",
        "phaseIds": [
          "startup-ask"
        ],
        "sourceFiles": [
          "ask-core.json"
        ],
        "contractPointer": "ask-core.json#startupContract",
        "appOwnedEvidence": [
          "Running app note."
        ],
        "passWhen": [
          "App behavior passes."
        ],
        "mustNot": [
          "Do not drain from data alone."
        ]
      }
    ],
    "finalDecision": {
      "expectedStatusBeforeAppWork": "pending-app-integration",
      "dataAloneIs
…

The schema

Its address is https://openvaluesstandard.org/schema/node-readiness-v0.1.schema.json. Validators can fetch it there; the file is also in the repository at app/data/standard/schemas/node-readiness.schema.json.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are used as described in RFC 2119 and RFC 8174 when, and only when, they appear in capitals.

Whether this format fits your app is your call. The spec says what a file MUST hold. Which formats you read and write, and what your app does with them, is yours to decide.