Validation guide.

Validate NCP payloads before exchange. The canonical schema catches missing required fields, invalid enum values, malformed timestamps, and accidental drift from the published storyform shape.

Quickstart

Clone the canonical repository, install dependencies, then validate either the repository fixtures or your own JSON files. Treat validation failures as blocking before import, export, or release.

$ npm install
$ npm run validate:schema
$ npm run validate:file -- /path/to/your-ncp.json

What validation protects

Envelope

Requires `schema_version` and the top-level `story` object.

Story metadata

Checks required story fields such as id, title, logline, created_at, and narratives.

Canonical enums

Rejects unknown appreciation, narrative function, dynamic, and vector values.

Layer shape

Keeps subtext and storytelling fields in their intended places.

Timestamps

Requires UTC ISO-8601 timestamps such as `2025-12-01T12:34:56Z`.

CI safety

The validator exits non-zero on failure, so pull requests can block invalid payloads.

Use validation in another repo.

If your project stores NCP files elsewhere, copy the canonical schema and file validator into that repository, install Ajv, and run the validator against every NCP file you publish or ingest.

npm install ajv
node tests/validate-file.js ./story.ncp.json

Reference CI pattern.

Continuous validation keeps storyform payloads from drifting after review. Run the same file validation command during pull requests and release branches.

name: Validate NCP

on:
  pull_request:
  push:

jobs:
  validate-ncp:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run validate:file -- path/to/your-ncp.json