Skip to content

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 2.0 namespace https://uwmd.org/ns/document/2. The current canonical files live in this directory pending publication on uwmd.org.

SchemaMirrorsSpec section
uwmd-block.schema.jsonBare payload + nested _meta (Format 3.0)Format §2.4–§2.6
uw-document-envelope.schema.jsonUWDocumentEnvelopeRFC 0014 / Envelope 2.0
uw-document-envelope.xsdStructural UW XML 2.0 tooling schemaUW XML Mapping 2.0
edit-operation.schema.jsonEditOperation (discriminated union)Protocol §V
protocol-error.schema.jsonProtocolErrorProtocol §XI
institution-config.schema.jsonCanonical institution config wire objectFormat C.6 / Protocol VI.3 / RFC0097
implementation-manifest.schema.jsonImplementationManifestProtocol §I.4
metric-dictionary.schema.jsonMetricDictionaryMetric dictionary / RFC 0078
conformance-case.schema.jsonPortable case with one ConformanceTargetProtocol §II.6a.4 / RFC 0078
conformance-corpus.schema.jsonExhaustive corpus ownership indexProtocol §II.6 / RFC 0078
calc-result.schema.jsonCalcResultProtocol §VIII
issue-remediation.schema.jsonIssueRemediationProtocol §III.6a
module-manifest.schema.jsonModuleManifestProtocol §X
module-signature.schema.jsonModuleSignatureProtocol §X.1
uw-document-signature.schema.jsonUWDocumentSignatureRFC 0084 / Signing 1
uw-receipt.schema.jsonUWReceiptUW Receipt 1.1 / RFC 0016
section-gaps.schema.jsonSectionGapsProtocol §VII
section-components.schema.jsoncomponents section (mixed-use)Format §4.23 / RFC 0019
section-capital-stack.schema.jsoncapital_stack section (tranches + sizing)Format §4.24 / RFC 0026
section-lease-up-schedule.schema.jsonlease_up_schedule section (trajectory + stabilized summary)Format §4.25 / RFC 0008
section-cash-flow-series.schema.jsoncash_flow_series section (dated flows + stated metrics)Format §4.26 / RFC 0034
section-reserve-accounts.schema.jsonReserveAccountsFormat §4.28 / RFC 0064
reserve-accounts-verification.schema.jsonReserveAccountsVerificationProtocol §VIII.11 / RFC 0064
stated-metrics-report.schema.jsonStatedMetricsReport (verify-metrics)Protocol §II.2 item 2, §II.6a.1 / RFC 0115
section-verification-report.schema.jsonSectionVerificationReport with CashFlowVerification, WaterfallVerification, CapitalStackVerification, LeaseUpVerificationProtocol §II.6a.1 / RFC 0115
receipt-verification.schema.jsonUWReceiptVerification (verify-receipt)UW Receipt §5, Protocol §II.6a.1 / RFC 0115
section-distribution-waterfall.schema.jsondistribution_waterfall section (tier ladder + stated outcomes)Format §4.27 / RFC 0035
rent-roll-hospitality.schema.jsonhospitality rent_roll class contract (room nights, ADR, occupancy; no keys)Format §4.3 / RFC 0081 G3
lease-escalation-schedule.schema.jsoncommercial tenant rent-step scheduleFormat §4.3 / RFC 0055
lease-recovery-terms.schema.jsoncommercial tenant expense-recovery termsFormat §4.3 / RFC 0058
lease-recovery-true-up.schema.jsonclosed-period CAM reconciliation rowsFormat §4.3 / RFC 0058
lease-termination-option.schema.jsoncommercial tenant break optionFormat §4.3 / RFC 0055
lease-co-tenancy.schema.jsoncommercial tenant co-tenancy trigger and remedyFormat §4.3 / RFC 0055
tax-reassessment.schema.jsonnoi_model reassessment basis (going-in)Format §4.5 / RFC 0053
tax-abatement.schema.jsonnoi_model abatement scheduleFormat §4.5 / RFC 0053
tax-terminal.schema.jsondcf.exit_analysis.terminal_tax (the next buyer's)Format §4.9 / RFC 0053
debt-rate-hedge.schema.jsondebt_structure.rate_hedge (cap strike, notional, term)Format §4.7 / RFC 0056
sources-uses-escrow.schema.jsonone entry of sources_uses.uses.escrowsFormat §4.8 / RFC 0056
renovation-draw.schema.jsonsources_uses.uses.renovation (budget, contingency, draw)Format §4.8 / RFC 0057
expense-targeted-capex.schema.jsoncapex bought to reduce a named operating expenseFormat §4.8 / RFC 0057
uw-deal-package-manifest.schema.jsonUWDealPackageManifestRFC 0018
uw-portfolio-profile.schema.json.uwportfolio.json sidecar (PortfolioProfile)Protocol §XV / RFC 0015
document-fact-term.schema.jsonClosed attributable term, locator and null statusRFC0129 / Format source-fact profiles
document-facts-loan-quote.schema.jsonloan-quote-v1 logical payloadRFC0129 / Format4.7
document-facts-offering-memorandum.schema.jsonoffering-memorandum-v1 logical payloadRFC0129 / Format4.1,4.6,5.5
document-facts-appraisal-abstract.schema.jsonappraisal-abstract-v1 logical payloadRFC0129 / Format4.6
uw-market-data.schema.jsonmarket-data-v1 documentsRFC 0022
uwpart.schema.json.uwpart.md frontmatterUW Composition 1.0 §2 / RFC 0021
uw-external-section.schema.jsonexternal section directiveUW Composition 1.0 §3 / RFC 0021
uw-rollup.schema.jsonportfolio_rollup payloadUW Receipt 1.1 §11 / RFC 0021 §6
period-key.schema.jsonPeriodKeyProtocol §VIII.2a / RFC 0041
period-series-entry.schema.jsonPeriodSeriesEntryProtocol §VIII.2a / RFC 0041
period-refinement-issue.schema.jsonPeriodRefinementIssueStarter guide §VIII.2b / RFC 0042
section-refinement-issue.schema.jsonSectionRefinementIssueStarter guide §VIII.2b / RFC 0066
period-excel-binding.schema.jsonPeriodExcelBindingStarter guide §VIII.2c / RFC 0043
period-column-snapshot.schema.jsonPeriodColumnSnapshotStarter guide §VIII.2c / RFC 0043

| section-dc-capacity.schema.json | RFC 0080 standard dc_capacity payload | RFC 0080 | | section-dc-power.schema.json | RFC 0080 standard dc_power payload | RFC 0080 | | section-dc-revenue.schema.json | RFC 0080 standard dc_revenue payload | RFC 0080 | | section-hotel-metrics.schema.json | RFC 0080 standard hotel_metrics payload | RFC 0080 | | section-hotel-brand.schema.json | RFC 0080 standard hotel_brand payload | RFC 0080 | | section-hotel-food-beverage.schema.json | RFC 0080 standard hotel_food_beverage payload | RFC 0080 | | section-mhc-sites.schema.json | RFC 0080 standard mhc_sites payload | RFC 0080 |

| pro-forma-claim.schema.json | Explicit bounded L1 claim | RFC0092 | | pro-forma-report.schema.json | Completed assessment or typed refusal | RFC0092 | | section-dcf.schema.json | DCF profile extension | RFC0092 | | debt-structure-ltv.schema.json | Same-loan LTV basis | RFC0092 | | section-sources-uses.schema.json | Explicit total project cost | RFC0092 |

Validating a schema ​

bash
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/verify's 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.

Reserve draw bindings (RFC 0065) ​

  • Plan: optional digested selected-draw/expenditure inventories and explicit allocation edges.
  • Verification: independent state, digest, finite source evidence and RDB findings.

Shapes alone do not establish exact references, producer gross meaning, complete draw allocation or currency-quantum agreement. No assembly admission changes.

Released under the MIT License.