--- title: ANNEX B. Data Contracts description: "# *The technical agreements that stabilize interfaces, reduce ambiguity, and enable useful interoperability* **Doctrine Claim:** Without a Data Contract, every system update is a potential outage for your partners. Contracts stop the \"silent drift\" of schemas and timestamps that breaks…" url: "https://anthonyveltri.com/guide/annex-b-data-contracts/" updated: "2026-05-03" category: "Architecture & Interfaces" tags: - contracts - governance - interfaces - "technical-debt" --- # ANNEX B. Data Contracts # *The technical agreements that stabilize interfaces, reduce ambiguity, and enable useful interoperability* **Doctrine Claim:** Without a Data Contract, every system update is a potential outage for your partners. Contracts stop the "silent drift" of schemas and timestamps that breaks mission tempo. This is the technical agreement that turns a data feed from a "leak" into a "product." --- # **1. Purpose of Data Contracts** Data contracts define the expectations for information flowing across boundaries. They create predictability where partner diversity, schema drift, and leadership-driven change would otherwise create chaos. ![A diagram titled "The Dual Interface Contract" shows two sections: The Data Contract, with technology icons and bullet points for schema, refresh rate, auth, error handling, and "Protects the System"; and The Human Contract, with handshake icons and bullet points for named owners, escalation path, change notice, outage protocol, and "Protects the Relationship." A note below states an interface fails if either contract is missing.](https://anthonyveltri.com/wp-content/uploads/2025/11/stewardship-data-vs-human-contracts-1024x572.jpg) The Handshake: Every interface needs two owners. One owns the Data Contract (Technical), and one owns the Human Contract (Relational). You need both to prevent failure. You should distinguish between the Data Contract (Schema, API) and the Human Contract (Escalation, Roles). The Full Interface. A stable interface requires two contracts: a Data Contract (Technical Schema) and a Human Contract (Roles & Escalation). This Annex covers the left side. Data contracts exist because: - systems evolve independently - partners update on different cadences - schemas drift silently - timestamps degrade - formats vary - upstream decisions ripple downstream Without data contracts: - small deviations cause large failures - ingest pipelines break - partners misunderstand requirements - errors cascade - analysts lose trust - mission tempo degrades Data contracts stabilize the technical boundary so humans can work with clarity and autonomy. --- # **2. Why Data Contracts Matter** Data contracts are essential for: - federation - useful interoperability - degraded operations - distributed decisions - interface ownership - preventing rework - preventing schema drift - protecting high tempo work - predictable partner integration Data contracts reduce: - ambiguity - unplanned outages - mismatched assumptions - brittle behavior - reprocessing - ad hoc fixes - politics around correctness They are the technical version of human contracts and must be paired with them. --- # **3. The Ten Required Elements of a Data Contract** ![A two column table or side by side boxes. Left side labeled “Federated vocabulary.” Right side labeled “Integrated vocabulary.” Example rows: “Forms and fields” ↔ “Logical data model” “Shared spreadsheet layout” ↔ “Physical model in a warehouse” “Domain glossary” ↔ “Ontology” “List of datasets” ↔ “Data catalog”](https://anthonyveltri.com/wp-content/uploads/2025/11/7-3-federated-vs-integrated-vocab-1024x572.jpg?t=1764976272) The Translation: A Data Contract acts as the Rosetta Stone between partners. It explicitly maps "Your Field Name" to "My Logical Model," preventing drift. You may be doing the same work under different names. A complete data contract defines ten expected behaviors. ### **1. Schema definition** Fields, types, optional vs required, maximum tolerances. ### **2. Geometry rules (if applicable)** Projection, resolution, topology expectations, tolerance for errors. ### **3. Time rules** Timestamp fields, timezone assumptions, publish window, acceptable drift. ### **4. Refresh cadence** Expected update frequency; acceptable minimum and maximum. ### **5. Versioning model** Major, minor, or patch level changes; deprecation rules. ### **6. Authentication and authorization** Methods, token refresh expectations, fallback conditions. ### **7. Error signaling** How unexpected conditions are communicated; expected error codes. ### **8. Fallback behavior** What happens if updates stop, timestamps drift, or schema partially degrades. ### **9. Publishing expectations** Minimum viable publication; required attributes during crises or high-profile cycles. ### **10. Change management** How contract changes are communicated, approved, and rolled out. If even one of these ten is missing, the boundary becomes fragile. --- # **4. Data Contract Altitudes** ![A vertical stack of three rectangles labeled “Conceptual,” “Logical,” and “Physical.” In the Conceptual box, show icons or labels like “Incident,” “Resource,” “Location,” with simple arrows between them. In the Logical box, show a simplified entity relationship style view, for example “Incident(incident_id, start_date, status)” linked to “Resource(resource_id, type, callsign).” In the Physical box, show logos or generic icons for a database, a GIS layer, and an API response snippet.](https://anthonyveltri.com/wp-content/uploads/2025/12/7-1-conceptual-logical-physical-1024x535.jpg) **Contract Layers:**A Data Contract lives at the Logical Layer (Schema/Rules), but it must support the Conceptual Layer (Mission Intent) and govern the Physical Layer (Database/API). **The Translation Ladder:** Leaders live in the Conceptual layer (Icons/Outcomes). Engineers live in the Physical layer (Database/JSON). The Architect lives in the Logical layer, translating between the two - same domain, three levels of detail. For a Golden Dataset isn't just a database (Physical). It is a clearly defined concept (Conceptual) with a strict schema (Logical) that everyone agrees on. Data contracts operate across three levels. ### **Altitude 1: Technical correctness** Operators and engineers ensure the data meets field level expectations. ### **Altitude 2: Process correctness** Managers ensure the contract is followed, updated, and communicated. ### **Altitude 3: Intent correctness** Leadership ensures the contract supports mission and strategic outcomes. Failures occur when: - leadership adds requirements without understanding downstream impact - managers fail to protect technical boundaries - operators do not understand the intent - schema changes are pushed outside of agreed processes This describes both mission systems **and** the FRN environment. --- # **5. Data Contracts and Doctrine** Data contracts directly support: - federation vs integration - useful interoperability - degraded operations - preventive and contingent design - interfaces and ownership - decision drag reduction - commitment over compliance A data contract is not a bureaucratic artifact. It is a stabilizing force that keeps the system coherent under stress. --- # **6. Business Example: Federal Register Notices (FRNs) and the cost of no data contract** ![A line graph shows performance over time. At one point, actual performance drops below the standard of performance, creating a gap labeled "Gap to be restored by problem solving.](https://anthonyveltri.com/wp-content/uploads/2025/12/problem-solving-deviation-01-1024x572.jpg) **The Reality Gap & The Deviation Gap:** A problem is not just "something bad." It is a measurable divergence (Green Line) from an expected standard (Blue Line). If you cannot draw this gap, you do not have a problem statement. **For this Annex, it is about Detecting Drift**. A Data Contract provides the "Standard of Performance" (Blue Line). Without it, you cannot measure when a partner's feed drifts into failure (Green Line). FRNs are a perfect high visibility case of failed data contracts. Common problems we saw: - leadership added fields on a whim, without verifying business need - new mandatory fields appeared during review cycles - teams used inconsistent definitions for the same fields - some attributes were non negotiable legally, others were preference based - timelines shifted without communicating impacts - operators and editors were forced to reverse engineer meaning - revisions cascaded across teams because there was no baseline These are classic failures that occur when a data contract is missing. To fix this, **our team** created a practical data contract even if we did not name it that: - locked required fields - defined optional fields - stopped leadership driven schema drift - clarified meaning of attributes - prevented unnecessary rework - stabilized expectations across editors, analysts, and leadership - ensured the FRN met legal standards without endless thrash - restored predictability What we created was a data contract for legal publication. It prevented chaos even though the content was not technical in the traditional sense. It was data. It required rules. FRNs succeed only when the schema is stable. --- # **7. System Example: iCAV and the federated ingest layer** In iCAV, data contracts took the form of: - partner specific ingest profiles - expected schema shapes - fallback acceptance rules - geometry tolerance - time drift tolerance - metadata expectations - caching rules - versioning logic These contracts allowed: - partners to publish imperfect data - ingest to tolerate upstream variation - the viewer to display partial truth - analysts to trust the picture - engineers to isolate failures Without data contracts, federation collapses. With contracts, it scales. --- # **8. Data Contract Template (Paste Ready)** Here is your reusable template for WordPress: --- **Data Contract Template** **Purpose:** Describe what this data supports and why it matters. **Schema:** Required fields: Optional fields: Data types: Range and tolerance: **Geometry (if applicable):** Projection: Resolution: Topology expectations: Error tolerance: **Time Rules:** Timestamp field(s): Timezone convention: Acceptable drift: **Refresh Cadence:** Expected update rate: Minimum cadence: Maximum cadence: **Versioning:** Major changes: Minor changes: Patch changes: Deprecation path: **Authentication:** Method: Token rotation: Fallback behavior: **Error Signaling:** Codes: Messages: Retry rules: **Fallback:** What happens when updates stop or degrade? **Minimum Viable Publication:** What must still be sent even when the system is stressed? **Change Management:** Notice window: Channels: Approval process: --- # **9. Cross Links** Data contracts are directly supported by: - Annex A: Human Contracts - Annex C: Interface Ownership - Principle 7: Interfaces break first - Principle 10: Degraded operations - Principle 12: Emergent resilience - Principle 14: Decision drag - Principle 19: Commitment over compliance Data contracts prevent technical drift. Human contracts prevent interpersonal drift. They must work together. --- # **10. Doctrine Diagnostic - For Reflection:** Ask yourself: Where in your system do people argue about data meaning? Where do fields change informally? Where do updates break downstream code? Where do external stakeholders introduce changes without impact review? These are signs of missing data contracts. Write the contract. Stabilize the boundary. Reduce the drag. ### Field notes and examples - [Field Note: The Human Cost of Interoperability (and the Legal Cost of Speed)](https://anthonyveltri.com/field-note-the-human-cost-of-interoperability-and-the-legal-cost-of-speed/) - [Human Contracts Under The Air Picture](https://anthonyveltri.com/human-contracts-under-the-air-picture/) - [Interfaces Break First: Designing For Partial Truth](https://anthonyveltri.com/interfaces-break-first-designing-for-partial-truth/) Last Updated on May 3, 2026 ### Related Posts [![A graphic with the text "ANNEX A Human Contracts" overlaying a background of abstract, interconnected blue and gray circuit and network patterns.](https://anthonyveltri.com/wp-content/uploads/2025/11/annex-a-human-contracts.jpg) #### ANNEX A. Human Contracts](https://anthonyveltri.com/guide/annex-a-human-contracts/) [![ANNEX F Pattern Library" text over a background of interconnected geometric lines, circles, and digital patterns resembling a circuit or network schematic.](https://anthonyveltri.com/wp-content/uploads/2025/11/annex-f-pattern-library.jpg) #### ANNEX F. Pattern Library](https://anthonyveltri.com/guide/annex-f-pattern-library/) [![A diagram shows a translucent seated person labeled "Previous State: Unstructured Memory," a backpack labeled "Operational Assets: Field Repository," and five labeled cubes connected by arrows, representing stages of knowledge processing and organization.](https://anthonyveltri.com/wp-content/uploads/2025/12/the-backpack-featured-image-finally.jpeg) #### Field Note: Sorting the 20-Year Backpack](https://anthonyveltri.com/field-note-sorting-the-20-year-backpack/) [![A digital graphic with the title "ANNEX I High-Visibility Workflows" in bold text, overlaid on a background of abstract, interconnected lines and circles resembling a technical or technological schematic.](https://anthonyveltri.com/wp-content/uploads/2025/11/annex-i-high-visibility-workflows.jpg) #### ANNEX I. High Visibility Workflows](https://anthonyveltri.com/guide/annex-i-high-visibility-workflows/) [![A graphic with the title "ANNEX K System and Workflow Profiles" in bold text on a dark overlay, set against a background of abstract blue and black circuit and network diagrams.](https://anthonyveltri.com/wp-content/uploads/2025/11/annex-k-system-and-workflow-profiles.jpg) #### ANNEX K. System and Workflow Profiles (Case Studies)](https://anthonyveltri.com/guide/annex-k-system-and-workflow-profiles-case-studies/) [![A graphic with abstract blue and black data and circuit patterns, overlaid with a dark rectangle containing the text "ANNEX L Data Modeling & Vocab Crosswalk.](https://anthonyveltri.com/wp-content/uploads/2025/11/annel-l-data-modeling-and-vocab-crosswalk.jpg) #### Annex L: The Rosetta Stone for Data Teams: Bridging the Gap Between Technicians and Executives](https://anthonyveltri.com/guide/annex-l-data-modeling-and-vocabulary-crosswalks-in-federated-systems/)