[{"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","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":[]}]