--- title: Every Schema Property Has a History Worth Documenting description: Drawing on experience producing JSON Schema for 2,500+ BIG-IP objects at F5 Networks, the author argues that schema properties should carry provenance metadata... canonical: https://daily.dev/posts/every-schema-property-has-a-history-worth-documenting-jvzlw2wpf twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: Every Schema Property Has a History Worth Documenting | daily.dev og:description: Drawing on experience producing JSON Schema for 2,500+ BIG-IP objects at F5 Networks, the author argues that schema properties should carry provenance metadata... og:url: https://daily.dev/posts/every-schema-property-has-a-history-worth-documenting-jvzlw2wpf og:image: https://api.daily.dev/og/posts/jVzlw2WpF.png og:image:alt: Every Schema Property Has a History Worth Documenting og:image:width: 1200 og:image:height: 630 og:locale: en --- > ## Documentation Index > Fetch the complete documentation index at: https://daily.dev/llms.txt > Use this file to discover all available pages before exploring further. # Every Schema Property Has a History Worth Documenting **[API Evangelist](https://daily.dev/sources/apievangelist)** · 7 min read · 0 upvotes · 0 comments ## Summary Drawing on experience producing JSON Schema for 2,500+ BIG-IP objects at F5 Networks, the author argues that schema properties should carry provenance metadata — recording when a property was added, why, and who it serves. This history transforms schema evolution from archaeology into informed engineering. JSON Schema's tolerance for unknown keywords (via `x-` extensions) makes this straightforward without breaking validation. OpenAPI Overlays are recommended as the mechanism to keep provenance annotations separate from lean validation schemas, allowing two projections of the same object model: one rich with history for documentation and governance tooling, one clean for runtime validation. ## Full article daily.dev links to this article rather than hosting it. Read it at the original source: ## Questions this post answers ### How can I add custom metadata like history or provenance to a JSON Schema property without breaking validation? JSON Schema validators ignore keywords they do not recognize, so you can add a custom annotation keyword such as x-provenance directly alongside standard keywords like type, minimum, and maximum. The validator enforces the recognized constraints and steps over the extra field entirely, letting metadata such as when a property was added, why, and who depends on it ride along inert until tooling reads it. _Developers designing extensible schemas can find this kind of practical JSON Schema pattern discussion on daily.dev._ ### How can I keep documentation-rich schema metadata separate from the lean schema used for runtime validation? Use an OpenAPI Overlay: a separate document that targets nodes in an existing OpenAPI definition and adds or updates content without editing the original file. Keep the clean, minimal schema as the source of truth that services validate against, then maintain a separate overlay layering on annotations like x-provenance, applying it only when generating documentation, discovery, or governance views. _Teams weighing how to enrich OpenAPI specs without slowing validation can follow overlay patterns like this on daily.dev._ ## Similar posts on daily.dev - [JSON Schema Governs the Shape of Your Data](https://daily.dev/posts/json-schema-governs-the-shape-of-your-data-mxmz1qsyh) · API Evangelist · 0 upvotes · 0 comments - [Standalone JSON Schemas, Overlaid for Every Purpose](https://daily.dev/posts/standalone-json-schemas-overlaid-for-every-purpose-bnhnsyrzz) · API Evangelist · 27 upvotes · 1 comments - [Why JSON Schema matters more than ever in the age of generative AI](https://daily.dev/posts/why-json-schema-matters-more-than-ever-in-the-age-of-generative-ai-xskn2gm03) · The New Stack · 1 upvotes · 0 comments - [4 things you should be doing with JSON](https://daily.dev/posts/4-things-you-should-be-doing-with-json-fho46ojyc) · All Things Open · 1 upvotes · 0 comments - [What is a JSON Schema?](https://daily.dev/posts/what-is-a-json-schema--9luaxpkfs) · freeCodeCamp · 2 upvotes · 0 comments --- Tags: [#database](https://daily.dev/tags/database), [#openapi](https://daily.dev/tags/openapi) [View this post on daily.dev](https://daily.dev/posts/every-schema-property-has-a-history-worth-documenting-jvzlw2wpf) ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]} {"@context":"https://schema.org","@type":"TechArticle","headline":"Every Schema Property Has a History Worth Documenting","url":"https://daily.dev/posts/every-schema-property-has-a-history-worth-documenting-jvzlw2wpf","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/every-schema-property-has-a-history-worth-documenting-jvzlw2wpf"},"datePublished":"2026-07-14T12:45:43.768Z","dateModified":"2026-09-14T08:14:39.629Z","description":"Drawing on experience producing JSON Schema for 2,500+ BIG-IP objects at F5 Networks, the author argues that schema properties should carry provenance metadata...","image":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/adc550e316d1186975a01327e4ed2e8c?_a=AQAEuop","thumbnailUrl":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/adc550e316d1186975a01327e4ed2e8c?_a=AQAEuop","isAccessibleForFree":true,"articleSection":"API Evangelist","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"API Evangelist","logo":"https://media.daily.dev/image/upload/t_logo,f_auto/v1/logos/a36244ae67bc4f41a605f780267ecb5f","url":"https://daily.dev/sources/apievangelist"},"commentCount":0,"discussionUrl":"https://daily.dev/posts/every-schema-property-has-a-history-worth-documenting-jvzlw2wpf","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":0},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"database,openapi","timeRequired":"PT7M"} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"API Evangelist","item":"https://daily.dev/sources/apievangelist"},{"@type":"ListItem","position":3,"name":"Every Schema Property Has a History Worth Documenting"}]} {"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/every-schema-property-has-a-history-worth-documenting-jvzlw2wpf#faq","mainEntity":[{"@type":"Question","name":"How can I add custom metadata like history or provenance to a JSON Schema property without breaking validation?","acceptedAnswer":{"@type":"Answer","text":"JSON Schema validators ignore keywords they do not recognize, so you can add a custom annotation keyword such as x-provenance directly alongside standard keywords like type, minimum, and maximum. The validator enforces the recognized constraints and steps over the extra field entirely, letting metadata such as when a property was added, why, and who depends on it ride along inert until tooling reads it. Developers designing extensible schemas can find this kind of practical JSON Schema pattern discussion on daily.dev."}},{"@type":"Question","name":"How can I keep documentation-rich schema metadata separate from the lean schema used for runtime validation?","acceptedAnswer":{"@type":"Answer","text":"Use an OpenAPI Overlay: a separate document that targets nodes in an existing OpenAPI definition and adds or updates content without editing the original file. Keep the clean, minimal schema as the source of truth that services validate against, then maintain a separate overlay layering on annotations like x-provenance, applying it only when generating documentation, discovery, or governance views. Teams weighing how to enrich OpenAPI specs without slowing validation can follow overlay patterns like this on daily.dev."}}]} ```