Validation Rules Reference

Overview#

When Atlas checks your domain it produces violations, not warnings. A violation is a single problem found in your ontology.jsonld file or in one of your *.map.json instance map files, tagged with a rule ID such as I-B3 so you can look it up here.

Violations are hard-blocking, not advisory. Atlas validates your whole domain before it builds anything. If a single Error-severity violation is present, the build stops: you get an error response with the list of violations, and no world is built at all. Nothing is partially compiled, and no type or instance is "excluded" while the rest goes through. It is all or nothing.

The practical consequence: while you still have Error violations outstanding, fixing one of them will not make part of your model appear. Nothing appears until the last Error is gone. Until then, whatever was successfully compiled last continues to answer queries.

Almost every rule in Atlas is Error severity. There is exactly one Warning-severity diagnostic (I-B22, an unbound function parameter), and for reasons explained below you can never see it in a compile response.

Libraries are checked by the same rules through the same pipeline. Every O-A and O-B rule in this article applies to a library's ontology.jsonld as well as to a domain's.

Where violations show up#

This is the most important thing on the page, because saving and compiling fail in completely different ways. Do not assume that a successful save means your content is valid.

Saving succeeds even when the content is broken#

Atlas draft sessions are on by default. A save that fails validation is still written, but it is written into your own draft session rather than onto the branch. You get a normal success status code back. The only in-band signal that anything is wrong is the response header:

Atlas-Validation-Violations: 7

That header carries a count and nothing else. To see the actual list, use the validation read described below, or open the domain's Overview in the browser.

A save with a violation still reports Saved. The problem shows up on the domain's Overview, not in the drawer. When you are ready to move the work onto the branch, publish the draft explicitly:

POST /api/v1/branches/{branch}/draft/publish

Publish is branch-scoped. It promotes everything the session holds, across every domain and library you changed on that branch, and it revalidates the merged result as a whole. Read GET /api/v1/branches/{branch}/draft first if you need to know what that covers: changedDomains, changedLibraries and otherChangeCount name exactly what the publish will move, deletions included.

Note: a compile run inside a draft session builds your copy and leaves the shared compiled world in place, so a save and a compile can both succeed while your query results are unchanged. Publish the draft to make the change visible to everyone else.

There is one exception to a save being held in a draft: if rule O-A1 or O-A2 applies, the save is refused. Those two mean the ontology file cannot be read at all, so there would be nothing to edit your way out of.

Compiling returns 422 and builds nothing#

The compile route is:

PUT /api/v1/branches/{branch}/domains/{domain}/world

There is no body and the call is idempotent, so it is safe to run repeatedly.

On success you get 200 and a compile result (see "What a successful compile returns"). On failure you get 422 and a body of this shape:

{
  "type": "https://atlas.timebase.io/errors/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "3 violation(s) found in lonestar.",
  "violations": [
    {
      "ruleId": "I-B3",
      "severity": "Error",
      "filePath": "instances/equipment.map.json",
      "jsonPointer": "/3/properties/urn:atlas:ontology:plant:FlowRate",
      "instanceId": "pump-01",
      "message": "Property 'urn:atlas:ontology:plant:FlowRate' is not attached to type 'urn:atlas:ontology:plant:Motor' (instance 'pump-01'): attached to {'urn:atlas:ontology:plant:Pump'}, and 'urn:atlas:ontology:plant:Motor' is neither a declared-attachment type nor a subtype of one. A property may be declared on an instance only when it is attached to the instance's type or one of its supertypes.",
      "suggestion": null
    }
  ]
}

Asking for the list without compiling#

GET /api/v1/branches/{branch}/domains/{domain}/validation
GET /api/v1/branches/{branch}/libraries/{library}/validation

This is the channel you should build your fix-and-recheck loop on. It is cheaper than a compile, it changes nothing, it works on a domain you never wrote to, it survives a page reload, and it is the only place a Warning-severity violation is ever visible.

The response is:

{
  "branch": "main",
  "sha": "7f3d0884",
  "errorCount": 24431,
  "warningCount": 1,
  "blocking": false,
  "violations": [ ... ],
  "groups": [
    {
      "ruleId": "I-B6",
      "severity": "Error",
      "filePath": "instances/equipment.map.json",
      "defIndex": 3,
      "jsonPointer": "/3/properties/urn:atlas:ontology:plant:FlowRate",
      "count": 24428,
      "messages": [ "...", "...", "..." ],
      "suggestion": null
    }
  ],
  "omittedViolationCount": 23931,
  "omittedGroupCount": 0
}

Read groups, not violations#

One broken reference can fan out across every expanded row of an instance map. A field incident produced 97,712 outstanding violations on a single draft from a handful of real mistakes, and reading them as a flat list was neither useful to a person nor kind to the wire.

So the read collapses them. Everything sharing the same rule, severity, file and definition becomes one group carrying a true count, up to three distinct messages, and the first useful suggestion among its members. A violation that belongs to no single definition, such as an ontology-wide one, groups per distinct jsonPointer instead.

A violation can stand for more than one#

Each entry in violations is field-for-field identical to an entry in the 422 compile body, so you can handle both with the same code. Both now carry one more field:

Where a rule would otherwise emit thousands of near-identical errors, it now emits at most three real samples per failure site and one weighted summary for the rest. Every total you can read, errorCount, a group's count, the save header and the count in a 422 detail string, sums occurrences rather than counting entries, so the numbers stay honest while the response stays small.

If you total a violation list yourself, sum occurrences. Counting array entries under-reports, and on a fanned-out domain it under-reports by orders of magnitude.

The read is cached#

Repeat reads of the same commit are served from a cache rather than re-running the checks, which makes a fix-and-recheck loop and a polling dashboard both cheap. The cache key includes the commit, so anything you save produces a new commit and therefore a fresh run: you will never be handed a stale verdict for work you just did.

Two things worth knowing:

• A domain whose instance maps pull from a connector cannot be verified from the commit alone, so its verdict is only held for 60 seconds. A domain with no sourced maps is held for as long as that commit is asked about.
• Library validation is not cached. Every read runs the checks.

Reading a violation#

Every violation has the same seven fields.

Tip: filePath and jsonPointer together are the locator pair. They tell you which file to open and where in it to look. They are far more useful than the message text for finding the problem.

Note on quoted messages: the message text in the tables below is reproduced exactly as Atlas emits it, including punctuation, so you can search for it. Values in braces, such as {id}, are filled in at runtime with your own type, property or instance names.

How the checks run#

Validation runs in four ordered phases:

Phase 1: Ontology Format    ->  Is ontology.jsonld valid JSON-LD and well-formed?
Phase 2: Ontology Semantic  ->  Do the types and properties reference each other correctly?
Phase 3: Instance Format    ->  Are the instance map files structurally correct?
Phase 4: Instance Semantic  ->  Do instances use types and properties that actually exist?

Why clearing violations can reveal more#

Validation runs in phases, and three rules decide how far it gets. Each means that clearing what you can see can reveal a further batch.

1. The fatal halt. O-A1 and O-A2 are the only fatal rules in Atlas. If either fires, checking stops at the end of that phase and phases 2, 3 and 4 never run. Fix these first, always.

2. The per-file cross-phase skip. If any Phase 3 (instance format) rule fired against an instance map file, every Phase 4 (instance semantic) rule is skipped for that whole file. A file that does not parse cleanly cannot be checked for meaning.

3. Prerequisite chains. Some rules are silenced when the rule they depend on has already fired at the same spot. The full set:

   If this fired	These are skipped at the same spot
   I-B2 (unknown property URI)	I-B3, I-B4, I-B9, I-B15, I-B16, I-B17, I-B18, I-B22
   I-B9 (unknown function URI)	I-B22
   I-B19 (unresolved cross-node reference)	I-B20, I-B21
   I-B20	I-B21
   I-B5 (type is not a relationship)	I-B7
   I-B10 (binding path not advertised)	I-B11, I-B12, I-B13, I-B14

Tip: treat the violation list as a to-do list you re-fetch after each round of fixes, not as a complete inventory of everything wrong with your model.

Ontology format rules (O-A1 to O-A12)#

These rules check ontology.jsonld itself. They are most likely to fire if you edit the file by hand or if a write was interrupted. filePath is always ontology.jsonld. All are Error severity.

O-A1 and O-A2 are the only fatal rules in Atlas. They stop everything else from running, and they are the only rules that block a save inside a draft session.

Ask Gage

Ask the reviewer agent: "Check my ontology.jsonld against the O-A format rules (O-A1 through O-A12) and report any violations with their line numbers. I only want format problems right now, not semantic ones."

The reviewer scans the ontology structure without compiling and reports format issues first, which block everything else. Fixing format problems before semantic ones makes your to-do list shorter.

Function save rules (O-F1 to O-F6)#

These are the exception to everything above: they run in a synchronous pre-save validator, not in the compile pipeline. A function save that breaks one of them returns 422 with a violations[] array and persists nothing - it does not land in a draft session the way other ontology saves do.

Ontology semantic rules (O-B1 to O-B4, O-B6 to O-B10, O-B18 to O-B24)#

O-B18 to O-B21 check a property type's default sourcing strategy, and are the ontology twins of the instance-map rules named in each row. They behave like every other O-B rule: they block the write on the default path, and relax to a warning on save inside a draft session. See Property Sourcing Strategies for the feature itself.

These rules check that your types and properties refer to things that exist and form sensible structures. All are Error severity except O-B13, and the unbound-parameter case of O-B19.

There is no O-B5. Referential integrity on delete is covered by Atlas re-validating the whole domain after every write, together with the instance semantic family.

An ontology rule as the Overview shows it: O-B23, raised by a type that uses a property whose value is one of two scalars and pins neither.

Instance format rules (I-A1 to I-A11)#

These rules check that your instance map files can be read. filePath is instances/{name}.map.json. All are Error severity.

Instance semantic rules (I-B1 to I-B23)#

These rules check that a structurally valid instance map actually makes sense against your ontology and your connectors. All are Error severity except the second form of I-B22.

Remember the cross-phase skip: if any I-A rule fired against a file, none of these rules run against that file at all.

An instance rule as the Overview shows it: I-B10, raised by a source whose binding path no connector advertises. The advice line is the rule's suggestion field.

Connector-bound rules (I-A10, I-A11, I-B10 to I-B14)#

These seven rules only exist when instance maps pull their rows from a connector. They have one behaviour worth knowing about:

• With no connector context available, the I-B10 to I-B14 family does not run, so no violations from it are reported.
• With connectors registered but no external data store wired in, I-B10 runs and I-B11 to I-B14 do not.

The practical effect: the same domain can validate cleanly on one machine and produce a wall of I-B10 violations on another, purely because of what connectors are available. If a connector-bound domain validates surprisingly cleanly, check that your connectors are actually connected before you conclude the model is correct.

The warnings#

Atlas has four Warning-severity violations: the unbound-parameter cases of O-B19 and I-B22, I-B23's abstract-type case, and O-B13's reused inverse name. Because a compile only fails on Error severity, a domain whose only problem is a Warning compiles successfully and returns a normal 200 compile result. That result has no field that can carry a warning, so the warning is invisible on the compile path entirely.

The only way to see a Warning is GET .../validation. If your calculated values are unexpectedly coming out as zero and your compile is clean, this is the first thing to check.

What a successful compile returns#

A compile that passes validation returns 200 and this object:

{
  "entityCount": 634,
  "edgeCount": 73,
  "archetypeCount": 42,
  "compiledAt": "2026-08-03T09:14:22.881Z",
  "functionErrors": []
}

GET .../world returns the same counts plus three more fields for the cached world:

There is no warnings field on either response. If you are looking for per-item diagnostics in a successful compile, functionErrors is the only thing there.

functionErrors#

functionErrors is the compile's one soft-failure channel: a calculation function whose expression failed to compile is reported here, and the compile still succeeds. These entries do not have rule IDs and do not come from the validation pipeline, so you will not find them in the tables above and they never appear in a 422 body or in GET .../validation.

A function in this list is not calculating. Everything else in the domain still compiled.

Fixing violations#

1. Get the current list: GET /api/v1/branches/{branch}/domains/{domain}/validation
2. If blocking is true, fix the O-A1 or O-A2 violation first and fetch the list again. Nothing else was checked.
3. Fix the violations, using filePath and jsonPointer to find each one.
4. Save the ontology or instance map, through the browser interface or the API. Check the response for the Atlas-Validation-Violations header. If it is present, something is still outstanding.
5. Fetch the list again. Fixing a violation can reveal violations that were previously hidden behind it.
6. When the list is clean, publish your draft: POST /api/v1/branches/{branch}/draft/publish
7. Compile: PUT /api/v1/branches/{branch}/domains/{domain}/world

Compile is idempotent and safe to run repeatedly. If a compile fails, the previously compiled world keeps serving queries unchanged.

Troubleshooting#

• My save returned success but nothing changed on the branch. A save with outstanding violations goes into your private draft session and does not advance the branch. Check the response for an Atlas-Validation-Violations header, fetch GET .../validation to see what is outstanding, fix it, then publish the draft with POST /api/v1/branches/{branch}/draft/publish.

• I saved and compiled, both returned success, and my queries still show the old data. While you are working inside a draft session, a compile builds your own copy and leaves the world that everyone else queries in place. Publish the draft, then compile again.

• Where do I read warnings from? On a successful compile, the diagnostics are in functionErrors. On a compile with outstanding violations you get HTTP 422 and an array called violations. On a save you get a count in the Atlas-Validation-Violations response header, and the full list from GET .../validation.

• I fixed an error and none of my model appeared. Compile is all or nothing. Validation runs before anything is built, so a single Error means no world at all is produced. Nothing appears until the last Error is gone. Types and instances are never partially excluded.

• My compile call returns an HTML page instead of JSON. You are calling the retired POST .../compile route. Retired routes do not return 404 in Atlas: the single-page application shell is served instead, so you get 200 text/html. Use PUT /api/v1/branches/{branch}/domains/{domain}/world.

• The violation list is shorter than the number of problems I know about. Three things hide violations: a fatal O-A1/O-A2 stops all later checks (blocking will be true); an instance format error on a file silences every semantic check on that whole file; and prerequisite rules silence dependent rules at the same spot. Re-fetch the list after every round of fixes.

• My calculated property is always 0 and the compile is clean. You have most likely left a function parameter unbound. That is the I-B22 Warning, and a Warning can never appear in a compile response. Call GET .../validation and look at warningCount.

• My placeholder is not expanding and I only get one instance. Instance map placeholders use square brackets, [Num], not curly braces. A {Num} is treated as literal text, not a template, which is why nothing expands. Rule I-A8 reports the mismatched cases.

• I get I-B3 even though the property is in my ontology. The property exists (otherwise you would get I-B2) but is not attached to the instance's type. Attachment now lives on the entity type as a restriction, not on the property as rdfs:domain. If your ontology still uses rdfs:domain you will also be seeing O-A12. Remove rdfs:domain and attach the property from the type.

• The same domain validates cleanly on my machine but reports a wall of I-B10 errors on the server. The connector-bound rules do nothing when there is no connector context. A clean result on a machine with no connectors does not mean the binding paths are correct.

• entityCount is much larger than my instance count. That is correct. entityCount includes one entity for every property-strategy occurrence as well as one per instance. It is not a count of your instances and was never meant to be used as one.

Checking a domain against this reference#

Ask Gage

Ask the reviewer agent: "Scan my {domain-name} domain for any violations of the O-B (ontology semantic) and I-B (instance semantic) rules. Report each one with its rule ID, the affected type or property, and what the message says - but do not attempt to fix it."

The reviewer reads your model and cross-checks it against the rule families you just read about. It reports violations clearly without modifying anything, giving you a to-do list to work through.