UW Markdown — Schemas

Normative JSON Schemas for protocol types and a structural XSD for UW XML that cross integration boundaries. Tools written in any language can validate these contracts without reverse-engineering the reference TypeScript implementation.

The JSON schemas use JSON Schema 2020-12 and publish under the https://uwmd.org/schemas/ $id prefix. The XSD targets the UW XML 1.0 namespace https://uwmd.org/ns/document/1. The current canonical files live in this directory pending publication on uwmd.org.

Schema	Mirrors	Spec section
uwmd-block.schema.json	UWBlock + UWMeta (v1.x flat shape)	Format §2.4–§2.6
uwmd-block-v2.schema.json	UWBlock + nested UWMetaV2 + _overrides (format 2.0)	Format v2 §2–§3 / RFC 0009
uw-document-envelope.schema.json	UWDocumentEnvelope	RFC 0014 / Envelope 1.0
uw-document-envelope.xsd	Structural UW XML 1.0 tooling schema	UW XML Mapping 1.0
edit-operation.schema.json	EditOperation (discriminated union)	Protocol §V
protocol-error.schema.json	ProtocolError	Protocol §XI
implementation-manifest.schema.json	ImplementationManifest	Protocol §I.4
calc-result.schema.json	CalcResult	Protocol §VIII
issue-remediation.schema.json	IssueRemediation	Protocol §III.6
module-manifest.schema.json	ModuleManifest	Protocol §X
module-signature.schema.json	ModuleSignature	Protocol §X.1
uw-receipt.schema.json	UWReceipt	UW Receipt 1.0 / RFC 0016
section-gaps.schema.json	SectionGaps	Protocol §VII
section-components.schema.json	components section (mixed-use)	Format §4.23 / RFC 0019
section-capital-stack.schema.json	capital_stack section (tranches + sizing)	Format §4.24 / RFC 0026
section-lease-up-schedule.schema.json	lease_up_schedule section (trajectory + stabilized summary)	Format §4.25 / RFC 0008
section-cash-flow-series.schema.json	cash_flow_series section (dated flows + stated metrics)	Format §4.26 / RFC 0034
section-distribution-waterfall.schema.json	distribution_waterfall section (tier ladder + stated outcomes)	Format §4.27 / RFC 0035
lease-escalation-schedule.schema.json	commercial tenant rent-step schedule	Format §4.3 / RFC 0055
lease-recovery-terms.schema.json	commercial tenant expense-recovery terms	Format §4.3 / RFC 0058
lease-recovery-true-up.schema.json	closed-period CAM reconciliation rows	Format §4.3 / RFC 0058
lease-termination-option.schema.json	commercial tenant break option	Format §4.3 / RFC 0055
lease-co-tenancy.schema.json	commercial tenant co-tenancy trigger and remedy	Format §4.3 / RFC 0055
tax-reassessment.schema.json	noi_model reassessment basis (going-in)	Format §4.5 / RFC 0053
tax-abatement.schema.json	noi_model abatement schedule	Format §4.5 / RFC 0053
tax-terminal.schema.json	dcf.exit_analysis.terminal_tax (the next buyer's)	Format §4.9 / RFC 0053
debt-rate-hedge.schema.json	debt_structure.rate_hedge (cap strike, notional, term)	Format §4.7 / RFC 0056
sources-uses-escrow.schema.json	one entry of sources_uses.uses.escrows	Format §4.8 / RFC 0056
renovation-draw.schema.json	sources_uses.uses.renovation (budget, contingency, draw)	Format §4.8 / RFC 0057
expense-targeted-capex.schema.json	capex bought to reduce a named operating expense	Format §4.8 / RFC 0057
uw-deal-package-manifest.schema.json	UWDealPackageManifest	RFC 0018
uw-portfolio-profile.schema.json	.uwportfolio.json sidecar (PortfolioProfile)	Protocol §XV / RFC 0015
uw-market-data.schema.json	market-data-v1 documents	RFC 0022
uwpart.schema.json	.uwpart.md frontmatter	UW Composition 1.0 §2 / RFC 0021
uw-external-section.schema.json	external section directive	UW Composition 1.0 §3 / RFC 0021
uw-rollup.schema.json	portfolio_rollup payload	UW Receipt 1.0 §11 / RFC 0021 §6
period-key.schema.json	PeriodKey	Protocol §VIII.2a / RFC 0041
period-series-entry.schema.json	PeriodSeriesEntry	Protocol §VIII.2a / RFC 0041
period-refinement-issue.schema.json	PeriodRefinementIssue	Protocol §VIII.2b / RFC 0042
period-excel-binding.schema.json	PeriodExcelBinding	Protocol §VIII.2c / RFC 0043
period-column-snapshot.schema.json	PeriodColumnSnapshot	Protocol §VIII.2c / RFC 0043

Validating a schema

npx --yes ajv-cli compile -s spec/schemas/<name>.schema.json

CI runs JSON Schema validation on every PR. The UW XML codec tests and docs-site build cover the XML mapping; the XSD is also compiled during release verification.

Updating a schema

The TypeScript types in @uwmd/core/src/protocol.ts and types.ts are the canonical definition. When you change one of those types, update the matching schema here in the same PR. Drift between the two is a normative protocol bug.

If you add a new schema:

1. Place it next to the existing schemas, named <thing>.schema.json.
2. Use the https://uwmd.org/schemas/<thing>.schema.json $id.
3. Add a row to the table above.
4. CI picks it up automatically — no workflow change needed.

Step 3 is enforced: npm run verify-indexes fails when a schema is on disk without a row, or a row links a file that is not. Three schemas had drifted out of this table before that check existed, which is why it does now.

Lease-up projection (RFC 0044)

• Plan: explicit variant, day count and cash dates.
• Projection: candidate stream, source digest and bindings.
• Refusal: CALC-LU-PROJECTION with nested evidence.

Schemas check shape. Implementations additionally check exact period coverage, real calendar dates, source-order timing, verified amounts and digest agreement.

Property cash-flow assembly (RFC 0045)

• Plan: explicit sources, hold dates, basis and coverage.
• Assembly: copied cash rows and complete declared coverage evidence.
• Refusal: typed stage reason and nested diagnostics.

Schemas check shape; source identity, complete coverage and economic assertions need semantic validation. Declared completeness is not verified economics.