When to Use

• Authoring an ontology document (Neo4j Ontology Graph Specification) from a domain description
• Editing existing ontology YAML/JSON: nodes, relationships, properties, types, constraints, cardinality, extensions
• Validating an ontology document against the spec schema

When NOT to Use

• Cypher queries, or loading/applying an ontology into a database → neo4j-cypher-skill (ontology Cypher procedures do not exist yet — later work there)
• Generic graph modeling advice (node vs property vs label, anti-patterns, supernodes) → neo4j-modeling-skill

Authoring Workflow

Step 1 — Gather domain intent

Identify what is being modeled: entity types (nodes), connections (relationships + direction), properties per element, identifying keys, mandatory fields, cardinality. If the domain or required shape is unclear, ask the user what is being modeled and which questions the ontology must answer. Do NOT guess a domain.

Step 2 — Draft the document

YAML or JSON per user preference; default YAML (more readable). Apply the Core Facts below. Load references/format-reference.md when anything beyond the minimal example is needed (full labels object, constraint objects, extensions, full data-type grammar).

Step 3 — Validate

# From the skill directory:
uv run scripts/validate.py <document.{yaml,yml,json}>
# From the repo root:
uv run neo4j-ontology-skill/scripts/validate.py <document.{yaml,yml,json}>

Exit 0 = valid · exit 1 = schema violations (one line per field path) · exit 2 = parse/read/fetch error. PEP 723 script — uv resolves deps (jsonschema, pyyaml) itself.

The validator fetches the schema live — nothing is vendored. Resolution order: --schema <path-or-url> (explicit, no fallback) → the document's own schema field when it is a URL → the published current alias → transitional repo raw fallback. The document's schema URL decides which version it validates against: set it to the published versioned URL of the version being authored (older versions validate against their published schema).

Step 4 — Fix and re-validate

Fix every reported error; re-run Step 3. Repeat until exit 0. Validation is MANDATORY — never present an ontology as done with a non-zero exit.

Core Facts

• Required root fields: schema, id (unique ontology id string), version (STRING — user-defined revision label; quote it in YAML: version: "1"). Root rejects unknown fields (additionalProperties: false).
• schema value: the published URL of the version being authored, e.g. https://neo4j.com/docs/ontology-graph-spec/1.0.0/schema.json. Root key is plain schema, NOT $schema.
• nodes / relationships are maps keyed by LOCAL IDS, not labels/types. Label lives in label or labels.identifier; relationship type lives in type. Endpoints reference node ids (from.node / to.node) — label renames never break references.
• label: X is shorthand for labels: {identifier: X}. Use the full labels object only when implied or optional labels exist.
• Type tokens come from the Neo4jType enum exactly — case-sensitive. Tokens incl. STRING, INTEGER, FLOAT, BOOLEAN, DATE, DURATION, POINT, UUID; temporal tokens contain a space (ZONED DATETIME, LOCAL TIME); parameterized tokens use angle brackets (LIST<STRING>, VECTOR<FLOAT32>). UUID and VECTOR<...> have no LIST arm. No unions, no nested lists. dimension (integer|null) sits on the property, paired with VECTOR types.
• Constraints — two forms:
  • Flags on a property: key: true, unique: true, must_exist: true (snake_case — NOT mustExist). Single-property shorthands; key = unique + exists per Neo4j key-constraint semantics.
  • Object form: constraints is a MAP id → constraint object {type: EXISTS|KEY|PROPERTY_TYPE|UNIQUE, properties: [p1, ...], name: optional} — required for composites (≥ 2 properties) and nameable constraints. properties must name properties declared on the SAME element.
• Endpoint cardinality: count exact, or min_count/max_count ranged; absent = unconstrained (0..*).
• Extensions: fixed extensions shape per element — node: indexes/display/custom; relationship: indexes/custom; root: tables/mappings/custom; labels/property/constraint/index: custom only. Unknown extension keys rejected. custom is free-form — arbitrary owner data, never validated by the spec schema.
• Absent means none — never write empty maps/lists (properties: {}, aliases: [], custom: {}); omit them.

Minimal Example

library.ontology.yaml — 2 nodes, 1 relationship:

schema: "https://neo4j.com/docs/ontology-graph-spec/1.0.0/schema.json"
id: library
version: "1"
name: Library
nodes:
  author:
    label: Author
    properties:
      id: { type: STRING, key: true }
      name: { type: STRING, must_exist: true }
  book:
    label: Book
    properties:
      isbn: { type: STRING, key: true }
relationships:
  wrote:
    type: WROTE
    from: { node: author, max_count: 1 }
    to: { node: book }

Validates exit 0 via scripts/validate.py. Full YAML+JSON worked examples in references/format-reference.md.

References

Load on demand:

• references/format-reference.md — full field reference: every node/relationship/property/endpoint field, labels object, constraint objects, extension shapes, data-type grammar, gotchas, YAML+JSON examples
• Published schema base: https://neo4j.com/docs/ontology-graph-spec/ — immutable /<version>/schema.json per spec version, moving alias /current/schema.json

Spec Status

Published: the ONT-31 URLs above are live and are the canonical schema source. If the published host is unreachable, the validator falls back to the raw schema from neo4j/ontology-graph-spec main (moving). Ontology Cypher procedures do not exist yet; applying an ontology to a database is out of scope here.

Checklist

• Root fields schema, id, version present; version a quoted string; schema = the published versioned URL under plain schema key
• No unknown root fields; no $schema
• nodes/relationships keyed by local ids; relationship from/to reference node ids
• Every node has label or labels.identifier
• Type tokens exact from the Neo4jType enum (case-sensitive; spaced temporal tokens); dimension on the property with VECTOR types
• Flags only for single-property constraints; object form (type ∈ EXISTS/KEY/PROPERTY_TYPE/UNIQUE) for composites/named; constraint properties exist on the same element
• Extension keys match the element's fixed shape; arbitrary data only under custom
• No empty maps/lists written
• uv run scripts/validate.py <file> exits 0 (every reported error fixed and re-validated)