Understand the validator before you translate its instructions
How do you translate JSON Schema 2020-12 documentation, API validation guides and multilingual error messages without accidentally changing what data is accepted? Begin by separating the schema keywords and data keys that a validator interprets from human-readable annotations such as descriptions and titles. A translated sentence may help a reader understand a rule, but a translated property name can make the same record fail validation.
JSON Schema is a vocabulary for describing and validating JSON instances. Its 2020-12 specification includes keywords such as type, properties, required, $ref, $defs, oneOf, anyOf, allOf, if, then, else, unevaluatedProperties and format. Developers looking for JSON Schema translation, schema validation localization, format-checking rules or human-friendly validation errors need precise explanations that do not confuse annotation, assertion, evaluation and application business logic.
This practical guide shows how to localize schema documentation, translate errors without changing machine-readable paths, review international input and test multilingual examples. Its focus is JSON Schema’s own semantics rather than the separate products that embed or extend it. Different validators implement features and optional vocabularies differently; documentation should name the dialect and configuration being tested instead of assuming every tool behaves identically.
A map of schema, instance, annotation and output
A JSON Schema document declares expectations about other JSON data, called an instance. A validator evaluates the instance against the schema and may report results. A user-facing form or help article may also display translated labels. These are separate layers, even when they show identical words.
A property declaration such as customer_id inside properties defines a machine-recognized key. The title annotation ‘Customer identifier’ can be localized as human-readable text. A validation error path pointing to customer_id must still refer to the real key. A UI may choose a translated label while retaining that path for debugging.
Before editing, mark keywords, references, identifiers, regular expressions, enum values and instance property keys as protected contract material. Mark title, description, examples and custom display metadata as potential localization surfaces, subject to their actual application use. Even a string-shaped value can be a code rather than prose.
An app in Japan and one in Brazil can show different labels for the same profile form while both submit a JSON object with email_address. The schema and payload keys must remain those expected by the shared service unless the product has explicitly implemented a mapping.
1. A JSON Schema document is not merely a checklist
JSON Schema evaluation is defined through vocabularies and schema keywords, not by a plain-English interpretation of its structure. Keywords that look like ordinary words have precise functions. The word required, for instance, is not a description about what a company recommends; it is an assertion about which property names must be present.
Many schemas are valid JSON objects, but a syntactically valid JSON document is not necessarily a valid schema under the intended dialect. Likewise, a valid schema can express an unintended condition. Translation quality checks must include semantic validation and examples, not just JSON syntax checks.
Readers should be told which document is the schema and which is the instance. Show them side by side when possible. A schema’s properties object defines sub-schemas for named keys; an instance’s values are what the validator actually examines.
A multilingual support tutorial that calls the schema ‘the data’ can mislead users into editing the validation definition instead of their submitted record. Correct terminology is often more important than technical flourish.
2. The $schema keyword identifies the dialect
The $schema keyword identifies the meta-schema or dialect a schema intends to use. A guide about draft 2020-12 should preserve the exact URI that identifies that dialect. Translating the address or replacing its punctuation breaks machine recognition.
Different drafts have different keyword behavior, especially around arrays, references and evaluation. A tutorial copied from an older draft may look plausible while teaching the wrong rule. Label the draft explicitly on each runnable example and note when an application uses an embedded dialect.
Do not translate $schema as if it were a user-visible field name that should appear in submitted data. It is part of schema metadata. Explain its function in prose and leave the literal keyword unchanged.
A training exercise can run the same instance against two intentionally different schema drafts. The lesson should say which draft the validator selected. Avoid treating the tool’s default dialect as though it were universal.
3. $id supplies a base identity for references
The $id keyword can establish a schema resource’s identifier and a base URI against which relative references are resolved. It is not a decorative article URL. A translation that changes a $id just to make the address look local may redirect references or create a distinct resource identity.
Explain relative and absolute references through actual example locations. A slash, fragment, case change or percent-encoding mistake can matter. If a documentation page is hosted at a translated URL, that does not require the schema’s internal $id to become a translation of the webpage address.
Technical editors should inventory all references before moving schema files. A multilingual manual can link to the same canonical schema resource while presenting the explanation in several languages. Keeping identity stable prevents accidental fragmentation of the contract.
After publication, resolve every $ref in the chosen validator environment. A link that merely opens in a browser is not proof that a schema resolver will interpret the same base URI.
4. $ref means reuse a schema, not copy a paragraph
The $ref keyword points to another schema location and is evaluated according to the dialect’s reference rules. Its target is a URI reference, often including a fragment. Replacing a reference path with natural-language words can change which constraints apply.
A documentation author may explain that $ref reuses a definition of Address. That explanation can be translated. The literal URI reference and definition key are identifiers. If a reference points to #/$defs/Address, the exact path must match the schema resource’s declared structure.
Modern JSON Schema supports important interactions between $ref and adjacent keywords; avoid repeating oversimplified folklore that reference objects may never contain siblings. The meaning depends on the dialect, so check 2020-12 rules rather than an old blog post.
A translated purchase-order tutorial should run a positive and negative fixture through the referenced Address schema. That verifies both resolution and the intended constraints while keeping the surrounding educational prose accessible.
5. $defs stores reusable sub-schemas
The $defs keyword provides a place to define reusable schemas. Keys inside $defs are names that references can target. They may resemble English nouns, but they are not automatically suitable for translation inside executable examples.
A guide can present ‘Address’ as a label in different languages, yet the machine reference #/$defs/Address must still point to the real key. Renaming the key without updating references creates failure; updating both can still change externally referenced identities.
Use diagrams showing the root schema, the reusable definition and the reference path. Localize the text in captions. Do not translate slash-delimited reference fragments by swapping in grammatical word order from the target language.
A reviewer should verify that every relative and absolute reference resolves after the documentation’s translation, and that test fixtures still produce the expected passes and failures.
6. $dynamicRef and $dynamicAnchor add advanced reference behavior
Draft 2020-12 includes dynamic reference capabilities for situations such as extensible recursive schemas. Their names and semantics are not the same as plain $ref. A translated advanced guide should not reduce them to ‘links to definitions’ without explaining dynamic resolution scope.
A $dynamicAnchor provides a named dynamic anchor; a $dynamicRef can resolve through dynamic scope as defined by the specification. This mechanism is useful for extensibility, but the exact behavior depends on schema structure. The names and reference fragments are protected syntax, not target-language prose.
When teaching this feature, start with the ordinary reference graph and then show what changes when a schema extends an underlying structure. If the implementation does not support dynamic references correctly, document that limitation honestly rather than treating validation success as proof of compliance.
Reproduce a short example with base and extended schemas. Run both through a validator known to support the dialect, and explain why a chosen nested instance is accepted or rejected. That is better education than a glossary definition alone.
7. Type describes JSON categories, not arbitrary application classes
The type keyword restricts the instance to JSON Schema’s recognized types, such as object, array, string, number, integer, boolean and null. These tokens are schema keywords or type values, not labels to translate. JSON does not have every native type of every programming language.
Explain the distinction between JSON number and integer carefully. In JSON Schema, integer describes numeric values that are mathematically integral; it is not simply an alias for a particular machine-language int32. A validator’s handling of numeric precision may also depend on its implementation.
Localizing a field description as ‘whole number’ can be helpful. Replacing the literal type value integer with a translated word is not. Reviewers should compare the constraints before and after any documentation transformation.
A form may display a decimal number with a comma for a user’s locale while the JSON instance has to remain parseable under JSON syntax. Presentation formatting is separate from the serialized JSON numeric value.
8. properties declares named subschemas
The properties keyword maps property names to schemas describing their values. These names become instance keys that a validator can recognize. If a localized tutorial silently translates a key, the target object may no longer satisfy the original schema.
A multilingual API can supply localized display names through annotations or a separate UI layer. It need not translate the JSON field names themselves. When the product intentionally supports alternative input keys, document the normalization layer explicitly rather than pretending the original schema accepts them automatically.
Show a small example where total_amount is required and must be a number. Translate the display label ‘Total amount’ for people, but preserve total_amount in code. Then run a fixture with only a translated property name and observe the validation result.
Do not confuse declaring a property under properties with making it mandatory. That responsibility belongs to required or other relevant constraints. Clear differentiation prevents basic but costly misunderstandings.
9. required concerns presence of property names
The required keyword lists property names that must appear in an object. It does not, by itself, require a non-null value, a nonempty string or a positive number. Other constraints may enforce those conditions. A translated message that says ‘must be filled in’ can therefore misstate the rule.
Preserve the exact member strings of required, because they name properties. If the schema declares required [’email’], the literal key email is contractual. The localized error message may say ‘Please provide an email address’ if the UI maps that key correctly.
Test a missing property, a present property containing null, an empty string and a valid value. Their outcomes depend on the combination of required with type, minLength, format and other keywords. Do not attribute every failure to required.
In a public application form, wording matters. A label with an asterisk may be useful, but it should reflect the full set of rules, not just the existence of the required keyword.
10. additionalProperties and unevaluatedProperties are not twins
additionalProperties constrains object properties not matched by properties or patternProperties at that schema location. unevaluatedProperties uses evaluation results to address properties not already successfully evaluated under relevant schemas. They can differ significantly when composition is involved.
Translating both as ‘no extra fields’ loses the underlying mechanism. A guide should describe what counts as evaluated and show an example where an allOf composition interacts with property restrictions. Avoid teaching one as a drop-in replacement for the other.
Property names and validation keywords remain unchanged in runnable examples. The localized prose may explain which fields are allowed, ignored or rejected, but that explanation must be checked against actual evaluator results.
Run fixtures with one approved property, one unrecognized property and a property defined through a composed subschema. Compare outcomes. For complex schemas, the evaluation annotations need inspection rather than a guess based on visual nesting.
11. patternProperties means regular-expression matching
The patternProperties keyword associates regular-expression patterns with subschemas. Those patterns are not ordinary phrases for translation, and their behavior can be sensitive to escaping and the regular-expression language supported by the validator.
A pattern can match part of a property name rather than the whole name unless it is written with appropriate anchors. The tutorial should not imply that every pattern is implicitly exact. Also avoid converting punctuation or backslashes to target-language typographic equivalents inside code.
Different scripts and Unicode handling can change whether user-created keys match a pattern. When localizing documentation for global readers, show how the chosen validator handles non-ASCII property names without promising that every regular-expression engine has identical semantics.
Test properties that should match and narrowly miss the pattern. Then translate the sentence describing the rule, not the pattern itself. Give readers a reason for the anchors used in the example.
12. Array validation changed across drafts
Draft 2020-12 uses prefixItems for positional validation of an array’s leading elements and items for applicable additional elements. Older tutorials may use the earlier tuple-validation form of items. A translated guide should not combine syntax from separate drafts without explaining the difference.
Array item constraints are about data shape, not display order in a translated list. Moving elements to make a sentence read naturally can change which subschema applies to which index. Keep the executable fixture’s array order intact.
Use an example with a string code followed by an integer count. Show valid and invalid positional combinations. Then explain how items can constrain elements after the prefix, depending on the schema.
A multilingual API help page can reorder its narrative explanation while preserving the actual array contract. Readers should be warned when a positional array is difficult to maintain and a named-object structure might be a more maintainable API design.
13. contains, minContains and maxContains describe counted matches
The contains keyword checks whether array elements satisfy a supplied schema; minContains and maxContains can constrain the number of matching elements under the defined rules. This is different from applying a schema to every item in an array.
A translator may turn ‘at least one matching element’ into ‘every element must match’ by using an imprecise phrase. Explain the quantifier and include contrasting sample arrays. Preserve the literal keywords and numeric thresholds.
Some validators have different draft support or output details. In a guide about 2020-12, state which dialect is in play. If an example uses zero as a threshold, be careful to explain the exact consequent behavior rather than relying on common-sense intuition.
An order may need at least one line item with category safety. The schema can express a matching-element condition, but that is not equivalent to requiring all line items to be safety items. Verify the distinction with a few short fixtures.
14. oneOf, anyOf and allOf are different assertions
oneOf means exactly one subschema must validate; anyOf means at least one must validate; allOf means all supplied subschemas must validate. Those short definitions hide practical edge cases when subschemas overlap. A translated guide should use unambiguous quantitative language.
If two branches both accept an instance, anyOf succeeds but oneOf fails. An author who says oneOf merely means ‘choose an available option’ misleads developers. For allOf, multiple constraints can combine in ways that require careful evaluation and attention to annotations.
Use a test object that matches no branches, exactly one branch and two branches. Show each expected outcome before translating the text. Readers will understand more quickly from a truth table than from a paragraph with vague terms like ‘either’.
Do not translate the keywords in code or silently reorder branches. Even if branch order does not change the core Boolean result, error reporting and teaching examples can depend on which branch is being discussed.
15. not is a validation assertion, not an error sentence
The not keyword validates an instance only when the supplied subschema does not validate. It represents logical negation, not the human-language word ‘no’ in a pop-up. Negation can be difficult to translate naturally, especially in languages where double negatives behave differently.
Explain the schema’s actual exclusion rule in a positive sentence when possible, then show the corresponding invalid example. Keep the executable keyword unchanged and do not imply that not inserts or removes any property from the instance.
A simple schema might reject a particular forbidden shape. The lesson should state precisely which shape is forbidden and what remains allowed. Broad interpretations such as ‘all other data is safe’ exceed the meaning of one local condition.
Use a short test set with one instance matching the forbidden shape and another that does not. Explain why the negated result is reversed. A learner who can reason through those cases is less likely to misuse not.
16. if, then and else express conditional constraints
These keywords can express conditional validation. If the if subschema is satisfied, then can apply; otherwise else can apply, according to the relevant combination of present keywords. They do not execute application code or perform a workflow branch that edits the instance.
A translated article should clearly distinguish checking a condition from taking an action. For example, a schema might require a tax identifier when country_code has a particular value. It can validate that shape, but it cannot itself perform tax calculations or issue a legal determination.
Show two fixtures, one activating then and one activating else. Verify the result using the declared dialect. Avoid generic claims that any missing if, then or else has identical effects; use the exact keyword rules.
Conditional messages in the UI may require careful phrasing, particularly when explaining why one country asks for different information from another. Preserve the machine rule while translating the user-oriented rationale.
17. const and enum constrain literal values
const restricts an instance to a specified value; enum restricts it to one of a listed set of values. The literal values in those keywords may be identifiers, codes, strings, numbers or booleans. They are not automatically translatable display labels.
An enum value such as approved may look like ordinary English but could be a fixed API token. Translating it to another word in a JSON payload causes validation failure unless the service explicitly supports the alternative. A UI should map the token to the translated label separately.
Create a three-column glossary: serialized value, business meaning and localized display. For every target locale, compare submitted values to the canonical set. Include invalid values so readers see what the validator actually rejects.
A document status selector can show ‘Approved’ in any language while sending APPROVED as the contract code. This pattern supports clear interfaces without multiplying incompatible data schemas.
18. Numeric constraints are not formatting instructions
Keywords such as minimum, maximum, exclusiveMinimum, exclusiveMaximum and multipleOf constrain numeric values. A translation must distinguish inclusive from exclusive bounds and mathematical divisibility from mere decimal formatting.
Localization sometimes uses different decimal separators and digit grouping. Those presentation conventions do not change a JSON number’s syntax or the limit enforced by the schema. An instance containing a formatted string may fail a numeric type constraint, even though a person recognizes it as a number.
Use boundary tests: exactly equal to minimum, just below minimum, exactly equal to maximum, just above maximum and a multiple versus nonmultiple where appropriate. Explain rounding and floating-point concerns only within the actual validator’s behavior.
An age field with minimum 18 is not the same as one with exclusiveMinimum 18. A translation that drops the word ‘inclusive’ can reverse the policy readers implement.
19. minLength and maxLength are about JSON strings
JSON Schema string length constraints are measured in terms of Unicode code points under the specification’s model, not necessarily what a person perceives as visual characters or what a UTF-8 byte count reports. This distinction matters for combining marks, emoji sequences and multilingual user input.
A user might type one visible symbol composed of several code points. A validator can count it differently from what a designer calls a character. Translate the explanation carefully and avoid promising a particular on-screen glyph count.
String constraints do not themselves trim whitespace, normalize Unicode or enforce a particular language. Those behaviors come from other application rules. Explain them separately if the product applies them. Tests should include accented and multi-code-point examples.
A multilingual profile form limiting names must test real names in different scripts. A bare ‘maximum 20 characters’ message may be insufficiently precise if the UI and validator use different length calculations.
20. pattern constrains string content using a regex
The pattern keyword applies a regular expression to a string. It is not the same as the prose word pattern. As with patternProperties, matching is not automatically anchored to the full string. The expression’s escaping and engine compatibility deserve careful review.
Do not translate literals inside a regular expression unless the business policy explicitly changes. A fixed country-code pattern or restricted machine ID should stay canonical. A human-language input may require a more inclusive rule rather than a simplistic translation of an ASCII-only example.
Show accepted and rejected sample strings, including a Unicode name and a string with a leading or trailing character. Explain the role of ^ and $ where anchoring is intended. Avoid blanket claims about regex behavior across all validators.
If an existing pattern excludes valid international input, that is a schema-design issue to escalate and test, not something a translator can solve by changing the accompanying help text alone.
21. format may be annotation rather than assertion
Draft 2020-12 separates format annotation from optional format assertion behavior. A validator may recognize format metadata without rejecting an instance based on that format unless the appropriate vocabulary and configuration are active. Documentation must not promise that format: email automatically enforces a particular validation outcome in every tool.
Format checks can also be deliberately minimal. A string resembling an email address is not proof that the mailbox exists, belongs to the user or can receive messages. Translation should preserve this distinction between syntactic plausibility and real-world verification.
State the validator, configuration and format names when discussing actual enforcement. Test a malformed value, a plausible value and a case with international characters if the application supports them. Report what was observed, not what an annotation sounds like.
An international registration guide can say ‘enter a valid email address’ as a user instruction, but its engineering guide should not equate the JSON Schema format keyword with account ownership verification.
22. contentEncoding and contentMediaType are metadata
JSON Schema offers content-related annotations for strings, such as contentEncoding and contentMediaType, along with a contentSchema mechanism. These help describe embedded content; they do not automatically authorize arbitrary decoding or application execution merely because a string mentions an encoding.
An editor may mistake base64 encoded data for text that should be translated. A base64 string is a representation of bytes, not a new language. The correct documentation should explain the decoding and validation path without rewriting the contents as prose.
Protect literal media-type names, encoding identifiers and sample cryptographic material where they serve machine functions. Translate explanatory warnings about payload size, handling and trust boundaries. Test whether the actual validator asserts any constraints or only reports annotations.
A product accepting an image as encoded data needs server-side rules for file type, size and safety. A schema annotation alone is not an antivirus scan or an authorization check.
23. default and examples are annotations, not data mutation
The default keyword is an annotation in JSON Schema. The specification does not require validators to insert that value into an instance. Some tools may apply defaults as an additional feature, but a guide must not present that optional behavior as JSON Schema’s universal meaning.
Examples similarly illustrate expected data; they are not commands and are not automatically validated by every tool simply because they appear in a schema. Translators can sometimes localize illustrative human-facing content, but must preserve structure and constraints when the examples are meant to run.
Explain the distinction between a form builder using default to prefill a field and a validator checking an already supplied instance. If the product does both, state which library supplies the mutation behavior. A validation pass should not be confused with input normalization.
An application showing a preferred country in a dropdown may use an annotation as a hint. The submitted data still needs explicit validation. A translated example should show the value before and after any application-level defaulting.
24. title, description, readOnly and writeOnly guide humans
Annotation keywords including title and description can provide user-facing information. readOnly and writeOnly can help describe directional use of properties in some contexts, but the JSON Schema vocabulary should not be oversold as an authorization system or an automatically enforced HTTP access-control policy.
Translate titles and descriptions for the intended audience. Preserve actual property names and schema identifiers. For readOnly and writeOnly, explain that tools and API frameworks may interpret the annotations in application-specific ways; authorization belongs to the application and service.
Technical manuals should not imply a field is secure merely because it is annotated writeOnly. A client can still mishandle a secret, and a server must still enforce access controls. Keep sensitive data out of illustrative examples.
A login form may show a localized label for password while retaining the canonical key. Its backend must protect the credential independently of any JSON Schema annotation.
25. Validation error messages need two layers
A machine-facing validation result may include an instance location, schema location, keyword and structured details. A human-facing error can translate the cause into an actionable sentence. Do not overwrite the machine path to make it sound more natural; map it to a localized label for display.
An error about required might identify the missing property in a parameters object. A message ‘Your answer is invalid’ is less helpful than a specific correction, but an overconfident message can also mislead if the condition includes several possible failures.
Use an error catalog keyed by stable codes or schema paths, with localized sentences and variable placeholders. Escape untrusted values. Re-check plural forms, punctuation, right-to-left presentation and text expansion. A localized error should tell the reader how to fix the data, not simply translate a technical stack trace.
Test common failures: missing required key, wrong type, invalid enum value, extra property, length violation and wrong branch of oneOf. Ensure the displayed label leads the user to the real field in the form.
26. International data requires more than translation
Valid JSON can contain Unicode strings, but an application may still impose restrictions on addresses, names, postal codes, phone numbers and calendars. A schema copied from one country can inadvertently exclude legitimate inputs elsewhere. Translating the help page does not fix a discriminatory or inaccurate validator.
Review regexes, length constraints, country-specific formats, input normalization and numeric conventions with the target market’s actual requirements. Preserve the canonical service contract until changes are intentionally designed, tested and rolled out. Document any remaining country limitations honestly.
Do not invent a universal postal-code structure or name order. A person may have multiple family names or no family name. Address fields and validation messages should reflect what the product actually accepts, not a simplistic cultural stereotype.
An international onboarding example should include realistic synthetic names in several scripts, long addresses and boundary dates. Compare expected validator outcomes across locales before declaring the guide complete.
27. Case study: purchase-order variants
Imagine an order endpoint that accepts either a physical-goods order or a digital-delivery order under oneOf. Physical orders need a shipping address, while digital orders need a delivery email. A translated guide must preserve the exact discriminator and property names required by the shared service.
An imprecise statement that the order may contain either field can be wrong if both branches validate and oneOf then fails. Create test fixtures for exactly one branch, neither branch and ambiguous overlap. Adjust the schema design if a discriminator is needed; do not bury the issue in translation.
Give the reader a clear table of accepted shapes and localized descriptions. Code blocks keep the machine keys and enum values unchanged. The explanatory text can adapt to country context without introducing incompatible payload variants.
Verify that the real validator gives the expected result. A fluent paragraph is not a substitute for testing composition semantics.
28. Case study: a multilingual profile form
A public profile service uses required fields, strings with minLength, a language-code enum and an optional free-text biography. A translated page may display different labels and help examples, but the service should receive the same structural keys in all supported locales.
Test empty strings, absent keys, null, long names, combining characters and non-Latin scripts. Keep locale codes canonical and separate the code from the language name shown to users. If a validator’s string length differs from the UI’s perceived-character counter, document and reconcile that mismatch.
Error localization should preserve placeholders and paths while offering specific advice: which field is missing, what format is allowed or which value needs correction. Do not promise that a format annotation guarantees address or identity verification.
This case turns JSON Schema from an abstract topic into a reader’s experience of a form that is fair, understandable and technically consistent.
29. Case study: healthcare records and sensitive data
Consider a fictional appointment payload containing a patient identifier, appointment time, consent status and a notes field. Some strings may need translation for human support, while the identifier and consent codes must remain canonical. A timestamp cannot be safely replaced by a display-only local clock string.
Schema validation can ensure certain structural conditions, but it cannot establish that consent was ethically obtained, that a practitioner is authorized or that medical information is accurate. The educational article must keep structural validation separate from those business and legal responsibilities.
Use synthetic records and redact private fields in troubleshooting examples. Test boundary dates, optional values and error messages without revealing personal data. Confirm that localized explanations do not change the meaning of required consent fields.
A good tutorial teaches both precision and humility: schema validity is useful evidence about structure, not a blanket claim of safety or correctness.
30. Testing translated schemas and training readers
A practical course begins with an object schema and two sample instances. Mark which words are syntax, property names and human descriptions. Translate only the descriptions, then validate both instances. Next introduce required, enum, type and additionalProperties to see how assertions combine.
Move on to references, oneOf, arrays and unevaluatedProperties. Keep a table recording the validator version, selected dialect, input instance and observed result. A useful educational exercise includes at least one surprising failure where the instance looked reasonable but matched two oneOf branches.
Finally create a small error catalog and ask a bilingual learner to repair invalid inputs without seeing the source-language manual. Review whether every instruction identifies the right field and rule. This reveals unclear terminology, missing boundary cases and mismatches between validator and UI.
Before publication, verify $schema and $id identities, resolve references, preserve property names and enum values, test executable JSON examples and confirm the intended format-assertion behavior. Readers anywhere should learn the same contract.
Frequently asked questions
Can JSON Schema property names be translated? Only through an intentional application mapping or contract change. For ordinary documentation localization, preserve machine-readable keys and translate human labels and descriptions separately.
Does required mean the value cannot be null? No. required concerns property presence. Other constraints, such as type and minLength, determine whether null or empty text is acceptable.
Why does oneOf fail when two options match? oneOf requires exactly one matching subschema. anyOf permits one or more matches, while allOf requires all subschemas to match.
Is format: email always enforced? No. Draft 2020-12 distinguishes format annotation from optional assertion behavior. Check the validator and configured vocabularies, and do not equate basic format checks with real mailbox verification.
Does default insert data into my JSON instance? Not under the specification’s core validation semantics. Tools can offer optional defaulting behavior, but that is separate and must be documented explicitly.
Can translation change a $ref URL? Not casually. URI references identify schema resources or locations. Changing them can alter resolution. Translate surrounding prose while protecting references.
How do I translate validator errors? Keep stable error identifiers and machine paths; map them to understandable localized labels, instructions and placeholders. Test against actual invalid fixtures.
Where are the official rules? Consult JSON Schema 2020-12 Core and JSON Schema 2020-12 Validation. Use the dialect and validator support appropriate to the application.
The closing rule: preserve validation meaning
JSON Schema localization works when the schema’s constraints stay visible and dependable, human instructions become clearer and no translator mistakes an annotation for a validator action. Preserve identifiers, test the right dialect and explain exact outcomes. The final article should make correct data easier to submit in any language without silently changing which data the system accepts.