Read an AI JSON Output Contract Before Handoff

An AI-produced object can be valid JSON and still be unusable for the receiving workflow. It might omit a required field, supply a number as text, introduce an unexpected status or add a property that looks like approval. A declared output contract gives reviewers a more precise question than whether the response looks structured. This guide reads a small original JSON Schema and compares fictional objects with manual expectations. It does not run an AI model, contact a client system or authorize a record update.

Keep three stages separate: parsing the JSON text, checking the declared structure and verifying the meaning of the values. Passing one stage does not imply the others passed. A structurally acceptable identifier may still refer to nothing in the actual business. A permitted status word may be unsupported by source evidence. An integer count may have the wrong population. The contract is useful because it defines a boundary, not because it makes every claim inside that boundary true.

Write the receiving question before the schema

Begin with what the next step needs to read. For this fictional exercise, the receiving step needs an identifier, a status and a count. It is a read-only teaching handoff, not a real integration. The identifier field is named id, status is named status and count is named count. Those names are part of the authored contract. If an assistant chooses a different name because it sounds clearer, the result may fail the receiving expectation even when a person understands it.

The original schema declares a top-level object. It defines id as a string with at least one character, status as a string restricted to ready or review, and count as an integer with a minimum of zero. All three names are required. Additional properties are disallowed. The downloaded schema declares the 2020-12 dialect and contains only these deliberately small constraints. It is teaching material, not a schema copied from a client's application or a universal design recommendation.

For an actual project, decide each constraint with the receiving owner. Requiring a value without a legitimate source for it can encourage invented completion. Allowing a broad string where a receiving system needs a fixed category can hide incompatible outputs. Disallowing unknown properties can expose drift but can also require a deliberate versioning process. These choices are tradeoffs to specify and test, not defaults that make every workflow better.

Distinguish properties from required properties

The primary JSON Schema object reference explains that properties describes named fields, while required separately identifies fields that must be present. It also describes additionalProperties for fields outside the declared set. These definitions support the narrow contract reading here. They do not establish that a particular business needs these names or that a schema validates the source of a value. The examples below keep the authored schema and manual expectations together so each result can be inspected.

A reviewer should read the top-level type as well as individual properties. A list containing one object is not the same top-level shape as an object. Similarly, a schema that describes a field without requiring it may permit omission. A prompt saying always include everything does not change what the declared schema actually expresses. Align the prose instruction, schema and receiving assumptions before attributing a mismatch solely to the model.

Do not silently repair an omission by inserting a guessed default. That creates a different object and may create a claim the source did not support. If an actual workflow uses defaults, record the rule, its owner and the meaning of the substituted value. This teaching contract has no defaulting or coercion step. A missing required value is identified as missing rather than changed into zero, an empty string or an invented identifier.

Case A: zero can satisfy a required numerical field

The first fictional object has id K1, status ready and count zero. Under the authored contract, its shape and values satisfy the listed constraints. Zero is an allowed nonnegative integer and the count property is present. A reviewer should not call it missing merely because zero has a false truth value in some programming contexts. The existing missing/null/false/zero guide addresses that representation distinction; this example shows how it interacts with a declared output contract.

The manual expectation is structurally acceptable under this small schema. It is not that K1 exists in a real system, that anything is ready or that a real population contains zero items. None of those facts is supplied. Keep the structural result in a separate field from any semantic verification. This prevents a successful schema check from becoming an accidental statement that the object is factually correct or approved for an action.

For a real evaluation, preserve the exact candidate object and the schema version used to check it. An explanation such as valid response is too broad unless it says what validity means. A useful report might name parsing status, structural result and remaining source checks separately. This article's checks concern only the authored fixtures. No actual model response or production validation result is presented as evidence.

Case B: omitted and null values fail for different reasons

Case B contains two original variants. In B1, count is omitted from an otherwise similar object. In B2, count is present with the JSON value null. The manual expectation rejects B1 for the missing required property and B2 for the count type. These are distinct failures even though neither gives the receiver an allowed count. Keeping the reasons separate makes a later correction more precise than labeling both as incomplete output.

Null is a value, not the absence of a property. A contract can explicitly allow null when that meaning is appropriate, but this authored count field does not. Required would still matter in a nullable design: requiring a property and permitting null are different choices. Do not infer a universal preference from this example. Decide what unknown, unavailable and intentionally empty mean in the actual workflow before choosing how to represent them.

A correction request for B1 can ask for the missing value only if the source supports one. A correction request for B2 can ask whether the source is unknown and whether the contract should represent that state. Neither request should instruct the assistant to fabricate a nonnegative integer simply to pass a check. Sometimes the right result is an unresolved handoff or a revised contract, subject to the real owner's decision and evidence.

Case C: text zero is not numerical zero

The third fictional object uses the string 0 for count rather than the numerical value zero. Its JSON text may parse successfully, but it does not satisfy the authored integer constraint. The manual expectation is a type failure. This guide does not run a receiving application or show whether a particular application would coerce the value. The contract deliberately contains no conversion step, so conversion must not be assumed in the explanation.

The primary numeric reference distinguishes JSON Schema's integer and number concepts and shows that numerical strings are different from numbers. It also notes that a value with no fractional part can meet the integer concept even if written with a decimal point. Do not substitute a programming language's exact runtime type test for every part of the JSON Schema specification. The fixture checks here are explicitly limited to their supplied values, not a full validator conformance suite.

If a real receiving system does accept a conversion, document where it happens and what inputs it permits. A conversion that accepts a simple decimal string may behave differently for spaces, signs, exponents or malformed text. Those questions need their own tests if relevant. They are outside this fixture. The immediate review finding is narrower: the supplied string does not meet the declared count type without an additional, separately specified transformation.

Case D: an extra approval-shaped field is still extra

The fourth fictional object adds approved set to true. The schema allows only id, status and count, so the manual expectation rejects the additional property. The word approved is deliberately chosen to show how a plausible-looking field can carry a larger implication. This article asserts no actual approval process and does not treat the field's presence as evidence that anyone reviewed or authorized an action.

Disallowing extra properties can make an unexpected field visible at the structural stage. It is not a security guarantee and does not prove that all permitted fields are harmless or truthful. An object without approved could still contain an unsupported ready status. Likewise, a schema permitting an extra field would not make that field authoritative. Authority depends on the actual workflow and evidence, not on whether a word appears inside a parseable object.

Do not repair Case D by silently dropping the field and reporting the original as valid. If a real transformation removes unsupported properties, preserve the original candidate, transformation rule and resulting object. The receiver may need to know that an unexpected assertion was made. This guide supplies no executable transformation utility and makes no claim that filtering fields protects a real integration. It simply records what the small contract accepts.

Case E: a fixed category set preserves exact choices

The fifth fictional object uses READY in capital letters. The allowed authored values are ready and review. The manual expectation is an enum failure. The example does not say that uppercase words are inherently invalid or that every status system should be case-sensitive in the same way. It says the specific supplied value is outside this specific fixed set. If a normalization policy is desired, it must be separately defined and checked.

The primary enum reference describes restricting a value to a fixed set. In a real project, the category names should be understandable to the process owner and compatible with the receiving step. Avoid adding a new category merely because it makes a difficult example easier to label. If a legitimate unresolved state exists, decide how to represent it deliberately rather than hiding it inside a permitted word with an improvised meaning.

An AI instruction can reproduce the exact allowed values and ask the assistant to identify when no permitted value is supported. That is an original instruction idea, not an observed successful response. A real evaluation should include examples near category boundaries and preserve the manual labeling basis. A schema can check membership in the set, but it cannot by that membership alone establish whether ready is the correct classification for the source material.

Case F: structural success leaves business truth unresolved

The final fictional object has id K1, status ready and count two. Like Case A, it satisfies the listed structural constraints. No underlying source records are supplied to verify the identifier, status or count. The expected result therefore pairs structural acceptance with unresolved business truth and no action authorization. This is the most important boundary in the guide: a valid shape can carry an unverified claim.

A separate semantic check would need the relevant source and definitions. Does the identifier refer to the intended entity? What does ready mean? Which items are counted, and as of what scope? Those questions cannot be answered by re-reading the same object's syntax. A real project may need additional business rules, source comparisons or review stages. This guide does not invent their outcomes or claim that a professional assessed them.

The same distinction applies to an array of objects. Checking each object's shape would not automatically establish cross-record uniqueness, completeness of an import or correct pairing with source records. The existing reconciliation and SQL-join guides cover related population questions. This article owns the declared output contract. Keep its success statement bounded so later stages know what they still need to verify instead of assuming a generic green status covers everything.

Keep parsing, structural checks and source review visible

A practical review record can name the candidate artifact, schema identifier, dialect, check result and remaining questions. If parsing fails, structural evaluation may not even begin. If structure fails, explain the relevant constraint without inventing a source value. If structure passes, move to whatever semantic review the actual task requires. Do not collapse these stages into one accuracy score or call every failure a hallucination without examining what actually happened.

Duplicate property names in raw JSON text are another separate concern. A parser can discard information before a later schema check sees an object. The dedicated duplicate-name guide handles that issue with its own limited teaching utility. This page's fixtures are supplied as unambiguous static JSON objects and do not test raw-text duplicate handling. Preserve the distinction so a structural check is not credited with verifying information that may have been lost during parsing.

For actual implementation, choose and configure an appropriate validator for the declared dialect, then test its behavior on relevant inputs. The local code used for this article checks only the supplied fixture contract and manual expectations. It is not a general JSON Schema implementation or a certification that a library implements the specification. No executable validator is published with the guide, and no external API or production record is accessed.

Use an AI instruction that does not reward invented completion

An original instruction can provide the exact schema, a bounded source excerpt and the task of drafting a candidate object. It can say not to invent an identifier or count and to identify unsupported required values separately. The receiving design must decide how such unresolved cases are handled, because an object-only output channel may not have room for an explanation. This is a workflow-design question, not something the assistant should resolve silently by guessing.

Avoid asking a model to make the output valid at any cost. That phrase can obscure the difference between correcting a representation and inventing a fact. Replacing the string 0 with the number zero may be a justified conversion if the source and policy support it. Filling a missing count with zero because zero passes the schema is a different claim. Keep the source basis and the transformation rule explicit for each correction.

When evaluating an actual model later, preserve observed outputs separately from the manual fixtures. A teaching object written by an editor is not a model result, and passing fixture checks is not model accuracy. The useful comparison asks which observed candidates meet structure, which preserve source meaning and which remain unresolved. Those outcomes can guide a design discussion without implying that a schema or prompt guarantees a successful deployment.

Version the contract when its meaning changes

A new required field, a renamed status or a changed null policy can affect both producer and receiver. Give the change a clear identity and update manual cases to show what should differ. If review becomes needs_review, the old Case E boundary is no longer the only category question. If count becomes optional, B1's expectation changes. Preserve the reason for that change rather than reporting that the old fixture simply started passing.

Keep structural compatibility separate from business compatibility. Allowing more properties may make an object pass a broader schema while leaving the receiver unsure what the added fields mean. Tightening a constraint may reject previously accepted objects even when their source facts remain true. A real migration needs appropriate planning and checks for its actual systems. This article does not perform one or claim that its small schema is a production-ready integration contract.

The finished teaching handoff consists of the original schema, six case groups, manual expectations and a narrow check record. A reader can inspect the boundary of each result and see why structural acceptance differs from source verification. That is a useful starting point for practical AI work. It does not establish identity, truth, completeness, security, professional review or permission to act, and it should never be presented as doing so.

Before sharing a review note, identify the exact object and the contract version together. A screenshot of a successful check without its input can be difficult to interpret after either changes. Keep the original supplied values available for comparison, record which narrow question was checked and state which questions remain open. If a colleague later changes a required field or an allowed status, ask for a fresh comparison against the revised contract instead of transferring the earlier result to the new object. This maintains a useful handoff without suggesting that structural acceptance establishes factual accuracy.

Frequently asked questions

Does valid JSON mean an output meets the receiving contract?

No. Parsing establishes a different result from checking the declared structure. A parseable object can omit count, supply a text value or add an unsupported property. This guide keeps those questions separate and uses manual fixture expectations. It does not test a real receiving application or an observed AI response.

Does required mean a property cannot be null?

Required concerns presence. The field's type and other constraints determine which present values are allowed. In Case B, omission and null fail for different reasons under the authored contract. A nullable field is a possible design choice, but it must be explicit and appropriate to the actual workflow rather than assumed.

Why is numerical zero accepted while text zero is rejected?

The authored count field requires a nonnegative integer value. Numerical zero meets that condition; the string 0 does not without a separate conversion. This guide assumes no coercion step. The fixture check is limited to supplied values and is not a full JSON Schema numeric-conformance test or a statement about every application.

Does removing an extra approved field make an object authorized?

No. Field acceptance and operating authority are separate questions. Case D rejects the additional property, but even a structurally acceptable ready status remains unverified without source evidence. A transformation should be documented if used, and no resulting object should be treated as permission merely because its structure passes.

Can the schema verify that K1 exists or that the count is correct?

Not from the supplied object alone. Case F passes the listed structure while business truth remains unresolved. The actual identifier, population and status definitions would need relevant source evidence and separate checks. This guide does not look up records, inspect a client dataset or authorize any destination write.

Was a general schema validator or AI system evaluated here?

No. The supplied schema, objects and expectations are original fictional teaching material. Local and downloaded checks implement only their narrow fixture comparison. They are not a complete validator conformance suite, observed model outputs, client results, professional review, security certification or approval of a production workflow. No executable utility is supplied.