Skip to main content
Version: v0.25.0 (Latest)

The Attribute Profile (L2)

The Semantic Catalog (L1) defines the organization's world: entities, attributes, and relationships. The L2 Attribute Profile is the use-case layer above it. Its job is to say: "for this use case, these are the actors, these are the relationships between them, and these are the constraints that apply here, tightened beyond the catalog defaults if the use case demands it."

Governance flow from L1 catalog through L2 profile to L3 set and L4 channel: jurisdiction, classification, and sdPolicy values set at the catalog entity flow through role bindings and role-scoped traversal selections, narrowing at each layer but never widening, reaching the wire form with full provenance.

What a Profile Does​

A profile is a use-case binding that composes one or more published catalogs into a named collection of roles and relationships.

Roles bind catalog entities to use-case actors. A role gives a catalog entity a use-case name (employee, employer) and optionally narrows it to one or more specialization subtypes. The employee role binds to the Person entity and specializes to the Employee subtype, so the role carries both the base Person attributes and the Employee-specific ones.

Relationships are selected, not redeclared. The profile selects which catalog relationships the use case includes, by name. Relationship semantics, cardinality, and localization are already defined on the catalog and are not repeated in the profile.

Overrides are narrow-only. A profile may tighten individual attribute constraints per role, but it cannot loosen anything already declared on the catalog. Making email MANDATORY for the employee role is a valid override; making a MANDATORY catalog attribute OPTIONAL is not. This ensures that governance constraints established at L1 can only be strengthened, never weakened, as they flow downstream.

Catalogs are pinned by version. The catalogRefs array pins exactly one version per source catalog. Resolution is deterministic: downstream layers that pin this profile version see a stable view of the catalog regardless of subsequent catalog revisions.

The profile does not select individual attributes. Attribute selection happens at the Attribute Set (L3) layer, which takes a published profile as its input. A profile is the governance boundary; a set is the selection surface.

These layers are authored over REST in this walkthrough. VDX presents a guided UI for the same layers; the concepts and the resulting model are identical.

Create, Publish, and Resolve the Profile​

The "Acme Employee" profile composes the catalog published in Catalog (L1). It defines two roles:

  • employee, bound to the Person entity, narrowed to the Employee specialization. Inherits all Person attributes plus the Employee-specific ones.
  • employer, bound to the Organization entity, narrowed to the Employer specialization.

It selects both catalog relationships (residentialAddress and employment) and applies one override: email is tightened from OPTIONAL (its catalog default on Person) to MANDATORY for the employee role in this use case.

Create​

POST /api/attributes/v1/profiles
{
  "name": "Acme Employee Profile (layered)",
  "description": "Use-case profile over the layered Acme catalog: employee (Person/Employee) + employer (Organization/Employer) roles, residentialAddress + employment relationships.",
  "catalogRefs": [
    { "catalogId": "5b8c...catalogId", "catalogVersion": 1 }
  ],
  "roles": [
    {
      "id": "employee",
      "name": "Employee",
      "entity": { "catalogId": "5b8c...catalogId", "entity": "Person" },
      "specializes": ["Employee"]
    },
    {
      "id": "employer",
      "name": "Employer",
      "entity": { "catalogId": "5b8c...catalogId", "entity": "Organization" },
      "specializes": ["Employer"]
    }
  ],
  "relationships": [
    { "catalogId": "5b8c...catalogId", "relationship": "residentialAddress" },
    { "catalogId": "5b8c...catalogId", "relationship": "employment" }
  ],
  "overrides": [
    { "roleRef": "employee", "path": ["email"], "conformance": "MANDATORY" }
  ]
}

Field reference​

FieldMeaning
catalogRefs[{ catalogId, catalogVersion }]. Pins one version per source catalog.
roles[].idThe use-case role identifier used throughout L3 traversal paths (e.g. "employee").
roles[].nameA human-readable name for the role.
roles[].entity{ catalogId, entity: "<EntityName>" }. The catalog entity this role is bound to.
roles[].specializesArray of specialization entity names to narrow the role. The role carries the base entity's attributes plus the specialization's additions.
relationships[]{ catalogId, relationship: "<relationshipName>" }. Selects a catalog relationship by name. The relationship's cardinality and localization are read from the catalog.
overrides[]{ roleRef, path: [...], conformance?, sdPolicy?, ... }. Narrow-only per (role, attribute path). The allow-list fields are conformance, sdPolicy, entryCodesSubset, sensitive.

The overrides entry { "roleRef": "employee", "path": ["email"], "conformance": "MANDATORY" } upgrades email from OPTIONAL (its value on the Person entity in the catalog) to MANDATORY for the employee role in this use case. Any attribute not listed in overrides reads through to the catalog value.

Publish​

Publish the profile to freeze it for downstream consumption.

PUT /api/attributes/v1/profiles/{profileId}/status
{ "status": "PUBLISHED" }

After publishing, the profile is immutable. Any subsequent changes require a new draft.

Resolve​

GET /api/attributes/v1/profiles/{profileId}/resolved

Override and Version-Pinning Precedence​

The profile is the second layer in the resolution order. When a downstream layer resolves an attribute's effective value:

  1. Catalog (L1) establishes the canonical value for valueType, overlays.i18n, sdPolicy, and all governance overlays.
  2. Profile override (L2) is the effective value for fields in the override allow-list (conformance, sdPolicy, entryCodesSubset, sensitive). Anything outside the allow-list reads through to the catalog unchanged.
  3. Set override (L3) may tighten further per selected traversal entry.
  4. VC channel (L4) is selection and claim mapping only; it does not override governance.

No layer widens what a layer above has declared. The version pin in catalogRefs means this profile always resolves the catalog at version 1, regardless of how the catalog evolves after publishing.

See Modeling Your World for the full precedence table.

The License Gate​

Creating and publishing a profile is a license-gated enterprise write, governed by the semantic-attribute-binding feature. Reading (get, list, resolve) is never gated. See Modeling Your World for the full gate behaviour.

Every write on this page uses the operator's OIDC bearer token:

Authorization: Bearer <operator access token>
Content-Type: application/json

The tenant is resolved from the token's tenant_id claim.

Next Steps​

  • Attribute Set (L2): pin this published profile, select traversal paths (including cross-relationship paths), and apply set-level narrow overrides
  • Modeling Your World: the full layer model, governance-overlay detail, and version-pinning precedence
  • Catalog (L1): the entity, attribute, and relationship definitions this profile composes