[{"name":"BasicAddress","desc":"Core postal address fields. Base type for all address structures.","properties":[{"n":"city","r":true,"t":"string"},{"n":"countryCode","r":true,"t":"string","info":"ISO 3166-1 alpha-2"},{"n":"line1","r":true,"t":"string"},{"n":"line2","t":"string"},{"n":"line3","t":"string"},{"n":"organization","t":"string"},{"n":"postalCode","r":true,"t":"string"},{"n":"state","t":"string"}]},{"name":"Address","desc":"Extended address with contact details and labeling. Used for entity mailing/billing addresses.","properties":[{"n":"email","t":"string"},{"n":"label","t":"string","info":"e.g. 'Headquarters', 'Billing', 'Shipping'"},{"n":"name","t":"string","info":"Addressee name"},{"n":"notes","t":"string"},{"n":"phone","t":"string"}],"ext":"BasicAddress","usedBy":["Business Entity.address","Employee.address","Franchise Group.billingAddress","Franchise Group.postalAddress","Purchase Order.dropShipAddress","Sales Order.SalesOrderLine.shipToAddress","Ship Order.shipToAddress","Shipment.shipToAddress","Vendor.physicalAddress","Vendor.shippingAddress"]},{"name":"AddressBook","desc":"Ordered collection of addresses with primary flag and identifiers. Used when an entity maintains multiple addresses.","properties":[{"n":"addressNo","t":"integer","info":"Sequence number within the book"},{"n":"identifiers","r":true,"t":"array","info":"Array of Identifier value objects"},{"n":"isDeleted","r":true,"t":"boolean","info":"Soft-delete flag"},{"n":"isPrimary","r":true,"t":"boolean"}],"ext":"Address"},{"name":"Phone","desc":"A phone number entry with label and primary flag.","properties":[{"n":"isPrimary","r":true,"t":"boolean"},{"n":"label","t":"string","info":"e.g. 'Mobile', 'Work', 'Fax'"},{"n":"phoneNumber","r":true,"t":"string"}]},{"name":"Email","desc":"An email address entry with label and primary flag.","properties":[{"n":"email","r":true,"t":"string"},{"n":"isPrimary","r":true,"t":"boolean"},{"n":"label","t":"string","info":"e.g. 'Work', 'Personal'"}]},{"name":"PersonName","desc":"Structured person name with title and middle name support.","properties":[{"n":"firstName","r":true,"t":"string"},{"n":"lastName","r":true,"t":"string"},{"n":"middleName","t":"string"},{"n":"title","t":"string","info":"e.g. 'Mr', 'Ms', 'Dr'"}]},{"name":"Contact","desc":"A full contact record combining name, phones, emails, address, and custom data. Used for vendor contacts, customer contacts, etc.","properties":[{"n":"address","t":"valueType","info":"Address value type"},{"n":"contactNo","t":"integer","info":"Sequence number"},{"n":"customData","t":"schema","info":"Extensible key-value data"},{"n":"emails","r":true,"t":"array","info":"Array of Email value objects"},{"n":"franchiseGroups","r":true,"t":"array","info":"Associated Franchise Group codes"},{"n":"isActive","r":true,"t":"boolean"},{"n":"isDeleted","r":true,"t":"boolean","info":"Soft-delete flag"},{"n":"isPrimary","r":true,"t":"boolean"},{"n":"name","t":"valueType","info":"PersonName value type"},{"n":"phones","r":true,"t":"array","info":"Array of Phone value objects"}]},{"name":"EntityDetail","desc":"Denormalized snapshot of a referenced entity's identity fields (id + code + name + alias + sequence). Embedded inline on the parent document to avoid a separate query for basic display information. Extends Identifiable (adds UUID id). Used for Location and Dictionary/Lookup entity references.","properties":[{"n":"alias","t":"string"},{"n":"code","r":true,"t":"string"},{"n":"name","r":true,"t":"string"},{"n":"sequence","t":"integer"}]},{"name":"Identifier","desc":"A labeled identifier value (e.g. tax ID, loyalty number, external system reference).","properties":[{"n":"isPrimary","r":true,"t":"boolean"},{"n":"label","t":"string"},{"n":"name","r":true,"t":"string","info":"Identifier type label"},{"n":"value","r":true,"t":"string"}]},{"name":"Payment","desc":"A payment tender line within a transaction — captures method, amount, and change.","properties":[{"n":"accountNo","t":"string"},{"n":"accountType","t":"string"},{"n":"amount","r":true,"t":"decimal"},{"n":"changeAmount","t":"decimal"},{"n":"code","r":true,"t":"string","info":"Payment method code"},{"n":"name","r":true,"t":"string","info":"Payment method display name"},{"n":"paymentCardType","t":"string","info":"e.g. Visa, Mastercard, AMEX"},{"n":"paymentDate","t":"datetime"},{"n":"sequence","t":"integer"}]},{"name":"Money","desc":"Amount with currency code. Used wherever a monetary value needs explicit currency context.","properties":[{"n":"amount","r":true,"t":"decimal"},{"n":"currencyCode","r":true,"t":"string","info":"ISO 4217 currency code"}]},{"name":"ConfigurationRef","desc":"Embedded reference from a configurable entity to its configuration record in the CONFIG subsystem. The `config` field carries a denormalized snapshot of the Config entity (id, code, name) so runtime services can resolve configuration without an extra round-trip; `templateCode` optionally names the Config Template the config was derived from, which lets consumers validate expected shape and discover available keys. This value type is the canonical shape of every configurable entity's link to CONFIG — do not declare ad-hoc configId strings on entities. Consumers that need richer linkage (environment scope, version pinning, override chain) should add fields here rather than on each entity.","properties":[{"n":"config","r":true,"t":"entityDetail","re":"Config","info":"Denormalized snapshot of the referenced Config record (id, code, name). Follows the standard entityDetail pattern so display never requires a lookup. The Config itself holds Actor, Environment, and resolved values."},{"n":"templateCode","r":false,"t":"string","info":"Code of the Config Template the referenced Config was derived from. Optional, but recommended so consumers can validate against the expected schema and discover which keys are available."}],"usedBy":[]},{"name":"ContentAudience","desc":"Audience targeting filter for any ContentDocument (Announcement, Content Post, Content Page). Works in conjunction with the document's inherited franchiseGroups and its targetLocations/targetRoles properties to resolve the final delivery or visibility set. Resolution: franchiseGroups (inherited) ∩ targetLocations ∩ targetRoles, plus includeUsers, minus excludeUsers. The scope field declares the primary targeting strategy used by the authoring UI. Generalized from AnnouncementAudience on 31 Aug 2026 when the publishing lifecycle was lifted into the ContentDocument base schema — the shape is unchanged, only the applicability is wider. For a Content Page the resolved set is a visibility filter rather than a delivery set: pages are not fanned out, so includeUsers/excludeUsers govern who can read the page, not who receives it.","properties":[{"n":"allLocationsInFranchiseGroup","r":true,"t":"boolean","info":"When true, audience expands to every Location within the matched franchiseGroups. When false, only Locations explicitly listed in targetLocations are included."},{"n":"excludeUsers","r":true,"t":"array","re":"User","info":"Explicit User exclusions removed from the resolved audience after all other filters apply. EntityRef array. Empty array by default."},{"n":"includeUsers","r":true,"t":"array","re":"User","info":"Explicit User additions appended to the resolved audience regardless of franchiseGroup/Location/Role filters. EntityRef array. Empty array by default."},{"n":"scope","r":true,"t":"enumeration","v":["all","franchiseGroups","locations","roles","users"],"info":"Primary targeting strategy. 'all' = entire Company; 'franchiseGroups' = inherited franchiseGroups only; 'locations' = explicit targetLocations; 'roles' = explicit targetRoles; 'users' = explicit includeUsers only."}],"usedBy":[]},{"name":"LicenseGrant","desc":"Embedded record of the licence a single installed instance holds — the entitlement layer of the licensing model, sitting between the Licensing Tier catalogue and the Subscription that funds it. This value type is the canonical shape of entitlement on every licensable installed instance (Application Installation, Connection); do not declare ad-hoc tier enums or licence fields on entities. It exists as a shared value type rather than as fields copied onto each holder for exactly the reason recorded in Connection's own notes about ConnectionCredentials — two holders already carry the same state, and a third would make the duplication permanent. Consumers needing richer linkage (usage counters, proration state, grandfathering metadata) should add fields here rather than on each entity. STATE OWNERSHIP: licenseStatus is SYSTEM-OBSERVED, written only by the billing system, never by an operator — it is the third axis in the effective-usability conjunction alongside the holder's own operator-intent status and its system-observed authStatus. ENTITLEMENT RESOLUTION: effective capability is the tier's includedFeatures, plus featureOverrides granted, minus featureOverrides revoked; caps come from the tier's limits unless an override supplies a different value. Overrides exist because enterprise contracts routinely deviate from the published ladder, and the alternative — minting a bespoke Licensing Tier per customer — would turn the catalogue into a customer list.","properties":[{"n":"effectiveFrom","r":true,"t":"datetime","info":"When this grant begins to resolve. Required because a grant with no start cannot be evaluated; set it to the moment of purchase for an immediate licence."},{"n":"expiresAt","t":"datetime","info":"When this grant stops resolving. Null means it inherits the funding Subscription's currentPeriodEnd, which is the normal case — grants renew with the contract rather than carrying their own dates. Set explicitly only for a trial or a term that deviates from the contract period."},{"n":"featureOverrides","r":true,"t":"array","info":"Array of LicenseOverride objects recording per-contract deviations from the tier's published entitlement — a feature granted above the tier, a feature revoked below it, or a limit raised for this customer. Empty array is the minimum default and means the grant resolves exactly to its tier. Overrides are deliberately recorded here rather than by minting a bespoke Licensing Tier per customer, which would make the product catalogue a customer list and break tier-level reporting."},{"n":"licenseStatus","r":true,"t":"enumeration","v":["unlicensed","trial","active","past_due","expired","cancelled"],"info":"SYSTEM-OBSERVED STATE — the actual entitlement state, written only by the billing system (purchase, renewal, dunning, cancellation, trial expiry). Never set by an operator; operator intent lives in the holder's own status property. unlicensed = the holder exists but nothing has been bought for it, which is why this value type is required on its holders: the container must exist so licenseStatus always has a home, exactly as ConnectionCredentials is required so authStatus always has one. trial and active both resolve as licensed. past_due resolves as licensed or not according to dunning policy, which is applied by the billing system writing this field rather than by consumers interpreting it."},{"n":"seats","t":"integer","info":"Licensed seat count where the tier is priced per seat. Null for a flat-rate tier. Enforcement compares this against the holder's actual user count; the cap semantics (hard, soft, advisory) come from the tier's matching limit row, not from here."},{"n":"subscription","t":"entityRef","re":"Subscription","info":"The commercial contract funding this grant. Null only for a self-serve trial that predates a contract. When set, the grant's expiry and funding validity derive from this Subscription — a grant whose Subscription is not status 'active' must not resolve as licensed."},{"n":"tier","r":true,"t":"entityDetail","re":"Licensing Tier","info":"The plan level granted, as entityDetail (denormalized id/code/name/sequence) so enforcement and display resolve without a catalogue round-trip — the dictionary-ref-uses-entity-detail convention. The referenced tier's owning blueprint must match the holder's: an Application Installation's tier must belong to that installation's Application, and a Connection's tier to one of its Connectors."}],"usedBy":[]},{"name":"LicenseOverride","desc":"One negotiated deviation from a Licensing Tier's published entitlement, carried in a LicenseGrant's featureOverrides array. Enterprise contracts routinely deviate from the published ladder — a capability granted above the tier, one carved out below it, or a cap raised for a single customer. Recording those as overrides against a standard tier keeps the Licensing Tier catalogue a product catalogue; the alternative, minting a bespoke tier per customer, turns the catalogue into a customer list and destroys tier-level reporting. Every override should carry a reason and the contract reference that authorized it, because an unexplained entitlement deviation discovered two years later cannot be safely removed by anyone.","properties":[{"n":"effect","r":true,"t":"enumeration","v":["grant","revoke","setLimit"],"info":"What this override does to the tier's published entitlement. grant = switch on a feature the tier does not include. revoke = switch off a feature the tier does include. setLimit = replace the value of a matching limit row. Resolution order is tier first, then overrides applied in array order, so a later override wins over an earlier one on the same key."},{"n":"key","r":true,"t":"string","info":"The feature key (for grant / revoke) or the limit key (for setLimit) this override acts on. Must match the vocabulary the tier itself uses — a feature key from the blueprint's supportedFeatures, or a limit key from the tier's limits array. An override on a key the product does not declare is dead configuration and should be rejected on write."},{"n":"authorizedBy","t":"entityRef","re":"User","info":"Who applied the override. Entitlement deviations are a commercial concession with revenue impact, so they carry attribution independent of the holder record's generic audit fields."},{"n":"contractReference","t":"string","info":"The contract, amendment or deal reference that authorized this deviation. Free text because the authority lives in an external contracting system. Strongly recommended — an override with no stated authority can never be safely removed."},{"n":"expiresAt","t":"datetime","info":"When this override lapses, after which the grant resolves to its plain tier. Null means it persists for the life of the grant. Use it for promotional or migration-period concessions so they expire by construction rather than by someone remembering."},{"n":"reason","r":true,"t":"string","info":"Why this deviation exists, in plain language (e.g. 'migration concession, legacy POS parity until cutover'). Required: the failure mode this field prevents is an override nobody can account for and therefore nobody dares remove."},{"n":"value","t":"integer","info":"Replacement cap, for effect 'setLimit' only. Null with effect 'setLimit' means uncapped. Ignored for grant and revoke."}],"usedBy":[]},{"name":"PurchasingDiscountEntry","desc":"One discount on a purchasing document — header or line — carried in the discounts[] arrays of Purchase Order, Vendor Invoice, Vendor Credit and Bill (header and PurchaseOrderLine / VendorInvoiceLine / VendorCreditLine / BillLine). This value type is the canonical shape of a purchasing discount; do not declare per-document discount sub-documents. It replaced eight duplicated inline schemas on 5 Oct 2026 (PurchaseOrderDiscount, VendorInvoiceDiscount, VendorCreditDiscount, BillDiscount and their fee counterparts) for the same reason LicenseGrant exists: four holders already carried the same state, and each new one would have made the duplication more permanent.\n\nIDENTITY. Unlike most value types this one declares an id, following the EntityDetail precedent. Entries are paired across documents — a Bill entry copies an invoice entry, an invoice entry bills a PO entry — and that pairing needs a stable handle.\n\nLINEAGE. sourceEntryId points at the entry on the UPSTREAM document this one was copied from or matched to: Vendor Invoice → Purchase Order; Vendor Credit → Vendor Invoice; Bill → Vendor Invoice or Vendor Credit. Null on a Purchase Order, and on any entry with no upstream counterpart. This gives every discount a traceable path from order to payable and lets matching pair entries by id rather than inferring from reason and level.\n\nWHAT THIS TYPE OWNS vs WHAT EACH DOCUMENT OWNS. Universal invariants live here: the Percent/Fixed field rules, percents never compounding, and the reason permitting the level it is used at. Document-specific behaviour stays in each holder's businessValidation and must NOT be pushed into this type: how the percent basis is computed (the PO nets cancelled quantity; invoices and credits have none), when Percent entries stop re-resolving (any line change on a PO, Draft only on an invoice, never on a Bill), sign (on a Vendor Credit a discount reduces the amount credited), and authored vs copied (a Bill copies every entry from its source).\n\nLEVEL DECIDES COST, NOT REASON. A header entry is below-the-line (matching only); a line entry belongs to line cost. Nothing on this type records cost treatment.\n\nSCOPE. Purchasing only. Sale-side discounts reference the Promotions Discount entity and follow different rules; a cross-domain DiscountEntry would share a name and little else.","properties":[{"n":"id","r":true,"t":"string","info":"UUID v4 identity of this entry, stable for the life of the holding document. Referenced by downstream entries' sourceEntryId."},{"n":"amount","r":true,"t":"decimal","info":"Discount amount — authoritative for the rollup at its level. AUTHORED and > 0 when discountType = 'Fixed'. CALCULATED as ROUND(percent / 100 × basisAmount) to the holding document's currency precision when discountType = 'Percent', or copied as-is where the holder copies from source."},{"c":true,"n":"basisAmount","t":"decimal","info":"The basis a Percent entry was resolved against. Its formula is defined by the HOLDING DOCUMENT and the entry's level, not by this type. NULL for 'Fixed'."},{"n":"description","t":"string","info":"Free-text note, e.g. the vendor's own wording. Not a substitute for discountReason."},{"n":"discountReason","t":"entityDetail","re":"Purchasing Discount","info":"WHY the discount was given. Must reference an active Purchasing Discount in the same Company that permits the entry's level — appliesToHeader for header entries, appliesToLine for line entries. Drives reporting, matching and GL mapping. Optional until reason dictionaries are seeded per Company."},{"n":"discountType","r":true,"t":"enumeration","v":["Percent","Fixed"],"info":"Whether the discount is expressed as a percent of a basis or as a fixed amount."},{"n":"percent","t":"decimal","info":"Percent as entered (10 = 10%), never a fraction. REQUIRED and > 0 and ≤ 100 when discountType = 'Percent'; NULL when 'Fixed'. The retained input from which amount is resolved."},{"n":"sourceEntryId","t":"string","info":"id of the entry on the upstream document this entry was copied from or matched to (Vendor Invoice → PO entry; Vendor Credit → invoice entry; Bill → invoice or credit entry). NULL on a Purchase Order and wherever no upstream counterpart exists. Required on Bill entries."}]},{"name":"PurchasingFeeEntry","desc":"One fee on a purchasing document — header or line — carried in the fees[] arrays of Purchase Order, Vendor Invoice, Vendor Credit and Bill (header and each document's Line sub-document). The fee-side counterpart to PurchasingDiscountEntry, created on 5 Oct 2026 under the same decision and following the same rules for identity (declares an id), lineage (sourceEntryId to the upstream entry) and ownership: universal invariants live here, document-specific behaviour (sign on a Vendor Credit, where a fee REDUCES the amount credited; authored vs copied on a Bill) stays in each holder's businessValidation. Level decides cost treatment: header fees are below-the-line, line fees belong to line cost. Do not declare per-document fee sub-documents.","properties":[{"n":"id","r":true,"t":"string","info":"UUID v4 identity of this entry, stable for the life of the holding document. Referenced by downstream entries' sourceEntryId."},{"n":"amount","r":true,"t":"decimal","info":"Fee amount. Must be > 0. Sign of its effect on the document total is defined by the holder (a fee reduces a Vendor Credit)."},{"n":"description","t":"string","info":"Free-text note. Not a substitute for feeType."},{"n":"feeType","t":"entityDetail","re":"Purchasing Fee","info":"The kind of fee (freight, handling, duties…). Must reference an active Purchasing Fee in the same Company that permits the entry's level — appliesToHeader or appliesToLine. Drives reporting, matching and GL mapping."},{"n":"sourceEntryId","t":"string","info":"id of the entry on the upstream document this entry was copied from or matched to. NULL on a Purchase Order and wherever no upstream counterpart exists. Required on Bill entries."}]}]