Profiles

Profiles are the contracts that govern every resource stored under a data source. They define which properties exist, how values are validated, and which contained structures travel with each record. Each ingested resource must reference a profile key, making profiles essential for data quality and interoperability.

Anatomy of a profile

A profile describes its type, properties, optional contained components, and any validation rules. The example below highlights common patterns.

{
  "description": "Healthcare provider practicing within the network",
  "properties": {
    "name": {
      "type": "humanname",
      "rules": [{ "required": true }]
    },
    "specialties": {
      "type": "array",
      "items": {
        "type": "code",
        "binding": {
          "vocabulary": {
            "key": "medical-specialty",
            "strength": "preferred"
          }
        }
      }
    },
    "acceptingNewPatients": {
      "type": "boolean"
    }
  },
  "contained": {
    "openingHours": {
      "cardinality": "0:1",
      "properties": {
        "monday": {
          "type": "object",
          "properties": {
            "open": {
              "type": "time",
              "rules": [
                {
                  "required": true
                }
              ]
            },
            "close": {
              "type": "time",
              "rules": [
                {
                  "required": true
                }
              ]
            }
          }
        }
      }
    }
  }
}

• properties — List each attribute and its data type. Use validation rules to enforce required fields, ranges, enums, or vocabulary bindings.
• contained — Declare embedded components with their properties and cardinality.
• description — Document the business meaning so stewards understand how the schema should evolve.

Designing robust profiles

• Validate early — Use rules and vocabularies to fail fast when data violates expectations. This keeps ingestion clean and downstream reconciliation easier.
• Plan for evolution — Introduce new optional properties before deprecating old ones. Coordinate schema updates with upstream producers to prevent ingestion failures.
• Document relationships — Capture how profiles connect using relationship definitions so downstream consumers understand the graph.

Related references

• List all collections API for canonical request and response structures.
• Clinia data types for complex types such as address, contactpoint, and humanname.
• Field validation basics to craft rules that enforce data quality at ingestion time.

Keep exploring