From 0502814969a0687c68fafe1ce1eaee12105558ee Mon Sep 17 00:00:00 2001 From: Diego Carvallo Date: Tue, 18 Nov 2025 22:53:10 +0000 Subject: [PATCH 1/6] docs(rfc-20026b): cleanup language around relationships and references --- docs/README.md | 225 ++++++++++++++++++++-------- schema/odcs-json-schema-v3.1.0.json | 4 +- 2 files changed, 167 insertions(+), 62 deletions(-) diff --git a/docs/README.md b/docs/README.md index c12808d..e2a7517 100644 --- a/docs/README.md +++ b/docs/README.md @@ -66,7 +66,7 @@ tags: ['finance'] | Key | UX label | Required | Description | |--------------------------------------|---------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| apiVersion | Standard version | Yes | Version of the standard used to build data contract. Default value is `v3.0.2`. | +| apiVersion | Standard version | Yes | Version of the standard used to build data contract. Default value is `v3.1.0`. | | kind | Kind | Yes | The kind of file this is. Valid value is `DataContract`. | | id | ID | Yes | A unique identifier used to reduce the risk of dataset name collisions, such as a UUID. | | name | Name | No | Name of the data contract. | @@ -363,7 +363,26 @@ Reference to an external definition on element logic or values. This section describes how to reference elements within a data contract schema. References enable you to create relationships between different parts of your data contract. > [!IMPORTANT] -> References are currently only supported within schema properties for foreign key relationships. +> References are currently only supported for foreign key relationships. + +### Fully Qualified Reference Notation + +ODCS uses a fully qualified notation with the `id` field and slash-separated paths for stable, refactor-safe references. + +**Format:** `
/[/properties/]` + +**Characteristics:** +- Uses the `id` field (optional, recommended for references) +- Slash-separated path +- Stable across renames and refactoring +- Resilient to array reordering +- Explicit and unambiguous + +**When to use:** +- Long-lived production contracts +- Complex contracts with many references +- When refactoring is expected +- Cross-contract references ### Reference Structure @@ -377,7 +396,7 @@ Where: * **``**: Path to the contract file (optional for same-contract references) * **``**: '#' symbol to mark entry into a contract (optional for same-contract) -* **``**: The defined path within the contract +* **``**: The fully qualified path within the contract ### External Contract References @@ -399,38 +418,34 @@ https://example.com/data-contract-v1.yaml ### Reference Examples -#### External Contract References +#### Same Contract References ```yaml -# Reference to an element in an external contract -'external-contract.yaml#schema.my-table' +# Reference to a schema object +'schema/customers_tbl' -# Reference to a specific column in an external contract -'external-contract.yaml#schema.my-table.my-column' -``` +# Reference to a property +'schema/customers_tbl/properties/cust_id_pk' -#### Same Contract References +# Reference to a nested property +'schema/accounts_tbl/properties/address_field/properties/street_field' +``` When referencing elements within the same contract, the file component can be omitted. +#### External Contract References + ```yaml -# Full reference within same contract -'#schema.my-table.my-column' +# Reference to an element in an external contract +'customer-contract.yaml#/schema/customers_tbl/properties/cust_id_pk' -# File and anchor can be omitted for same contract -'schema.my-table.my-column' +# Reference to a nested property in an external contract +'external-contract.yaml#/schema/accounts_tbl/properties/address_field/properties/street_field' ``` -### Shorthand Notation - -For improved readability, ODCS supports the following shorthand notation when referencing properties within the same schema. The shorthand notation allows for a more concise way to define relationships. It can be used in the `to` and `from` fields of a relationship. -The shorthand notation is `.`. - -These shorthand options are only available for properties within the same data contract. - ### Relationships between properties (Foreign Keys) -Properties can define relationships to other properties, enabling you to specify foreign key constraints and other data relationships. Relationships use the reference mechanism from RFC 9. +Properties can define relationships to other properties, enabling you to specify foreign key constraints and other data relationships. #### Quick Overview @@ -452,15 +467,36 @@ Relationships can be defined in two ways: |-----|----------|----------|-------------| | relationships | Relationships | No | Array of relationship definitions | | relationships.type | Type | No | Type of relationship (defaults to `foreignKey`) | -| relationships.to | To | Yes | Target property reference using `schema.property` notation | +| relationships.to | To | Yes | Target property reference (fully qualified or shorthand notation) | | relationships.from | From | Context-dependent | Source property reference - Required at schema level, forbidden at property level | | relationships.customProperties | Custom Properties | No | Additional metadata about the relationship | -#### Reference Notation +#### Reference Notation for Foreign Keys + +Foreign key relationships support two reference notations: + +**Fully Qualified Notation** + +Uses the `id` field with slash-separated paths for stable references: + +* `schema/users_tbl/properties/user_id_pk` - References the property with id `user_id_pk` in schema with id `users_tbl` +* `schema/accounts_tbl/properties/address_field/properties/street_field` - References nested properties -* **Simple reference**: `users.id` - References the `id` property in the `users` schema -* **Nested reference**: `accounts.address.street` - References nested properties -* **Composite keys**: Use arrays to define composite keys (arrays must have matching lengths) +**Shorthand Notation** + +For improved readability in foreign key relationships, ODCS also supports shorthand notation using the `name` field with dot-separated paths: + +* `users.id` - References the `id` property in the `users` schema +* `accounts.address.street` - References nested properties + +> [!NOTE] +> Shorthand notation is only supported for foreign key relationships. For all other references, use fully qualified notation. + +**When to use each:** +- **Fully qualified**: Production contracts, cross-contract references, when refactoring is expected +- **Shorthand**: Simple contracts, development, when names are stable + +**Composite keys**: Use arrays to define composite keys (arrays must have matching lengths) ### Examples @@ -470,11 +506,17 @@ When defining a relationship at the property level, the `from` field is implicit ```yaml schema: - - name: users + - id: users_tbl + name: users properties: - - name: user_id + - id: user_id_field + name: user_id relationships: - - to: accounts.owner_id # 'from' is implicit (users.user_id) + # Fully qualified notation (uses id, stable) + - to: schema/accounts_tbl/properties/owner_id_field + + # OR shorthand notation (uses name, concise) + - to: accounts.owner_id # Note: DO NOT include 'from' field at property level ``` @@ -484,10 +526,17 @@ A property can have multiple relationships: ```yaml schema: - - name: orders + - id: orders_tbl + name: orders properties: - - name: customer_id + - id: order_customer_id + name: customer_id relationships: + # Fully qualified notation + - to: schema/customers_tbl/properties/cust_id_pk + - to: schema/loyalty_tbl/properties/member_customer_id + + # OR shorthand notation - to: customers.id - to: loyalty_members.customer_id ``` @@ -498,23 +547,36 @@ Define relationships at the schema level when you need explicit `from` and `to`. ```yaml schema: - - name: users + - id: users_tbl + name: users relationships: - - from: users.account_id # Required at schema level - to: accounts.id # Required at schema level + # Fully qualified notation (stable) + - from: schema/users_tbl/properties/user_account_id + to: schema/accounts_tbl/properties/acct_id_pk + type: foreignKey + + # OR shorthand notation (concise) + - from: users.account_id + to: accounts.id type: foreignKey ``` #### Example 4: Nested Properties -Reference nested properties using dot notation: +Reference nested properties: ```yaml schema: - - name: users + - id: users_tbl + name: users properties: - - name: id + - id: user_id_pk + name: id relationships: + # Fully qualified notation + - to: schema/accounts_tbl/properties/address_field/properties/postal_code_field + + # OR shorthand notation - to: accounts.address.postal_code ``` @@ -524,16 +586,26 @@ For composite foreign keys, use arrays. **Important**: Both `from` and `to` must ```yaml schema: - - name: order_items + - id: order_items_tbl + name: order_items relationships: + # Fully qualified notation (stable) - type: foreignKey - from: # Array (must match 'to' length) + from: + - schema/order_items_tbl/properties/item_order_id + - schema/order_items_tbl/properties/item_product_id + to: + - schema/product_inventory_tbl/properties/inv_order_id + - schema/product_inventory_tbl/properties/inv_product_id + + # OR shorthand notation (concise) + - type: foreignKey + from: - order_items.order_id - order_items.product_id - to: # Array (must match 'from' length) + to: - product_inventory.order_id - product_inventory.product_id - ``` #### Example 6: Invalid Configurations @@ -580,39 +652,61 @@ schema: #### Complete Example -Here's a comprehensive example showing various relationship patterns: +Here's a comprehensive example showing various relationship patterns with both notations: ```yaml schema: - - name: users + - id: users_tbl + name: users properties: - - name: id + - id: user_id_pk + name: id + logicalType: integer relationships: - # Simple foreign key (from is implicit) - - to: accounts.user_id + # Fully qualified notation + - to: schema/accounts_tbl/properties/acct_user_id + description: "Fully qualified reference using id fields" - # With explicit from field - - from: users.id - to: profiles.user_id + # Shorthand notation + - to: accounts.user_id + description: "Shorthand reference using name fields" # With custom properties - - to: departments.manager_id + - to: schema/departments_tbl/properties/dept_manager_id customProperties: - property: cardinality value: "one-to-many" - property: label value: "manages" - # To external contract (from is implicit) + # To external contract (fully qualified) + - to: https://example.com/data-contract-v1.yaml#/schema/profiles_tbl/properties/profile_user_id + customProperties: + - property: description + value: "Externally referenced contract (fully qualified)" + + # To external contract (shorthand) - to: https://example.com/data-contract-v1.yaml#profiles.user_id customProperties: - property: description - value: "Externally referenced contract" + value: "Externally referenced contract (shorthand)" - - name: account_number + - id: user_account_number + name: account_number + logicalType: string # Schema-level composite key relationship relationships: + # Fully qualified notation + - type: foreignKey + from: + - schema/users_tbl/properties/user_id_pk + - schema/users_tbl/properties/user_account_number + to: + - schema/accounts_tbl/properties/acct_user_id + - schema/accounts_tbl/properties/acct_number + + # OR shorthand notation - type: foreignKey from: - users.id @@ -621,14 +715,25 @@ schema: - accounts.user_id - accounts.account_number - - name: accounts + - id: accounts_tbl + name: accounts properties: - - name: user_id - - name: account_number - - name: address + - id: acct_user_id + name: user_id + logicalType: integer + - id: acct_number + name: account_number + logicalType: string + - id: acct_address + name: address + logicalType: object properties: - - name: street - - name: postal_code + - id: addr_street + name: street + logicalType: string + - id: addr_postal_code + name: postal_code + logicalType: string ``` ## Data quality diff --git a/schema/odcs-json-schema-v3.1.0.json b/schema/odcs-json-schema-v3.1.0.json index 703281a..bde9d83 100644 --- a/schema/odcs-json-schema-v3.1.0.json +++ b/schema/odcs-json-schema-v3.1.0.json @@ -2652,7 +2652,7 @@ "oneOf": [ { "type": "string", - "description": "Source property reference using schema.property notation." + "description": "Source property reference using fully qualified notation (schema//properties/) or shorthand notation (table_name.column_name)." }, { "type": "array", @@ -2669,7 +2669,7 @@ "oneOf": [ { "type": "string", - "description": "Target property reference using schema.property notation." + "description": "Target property reference using fully qualified notation (schema//properties/) or shorthand notation (table_name.column_name)." }, { "type": "array", From d95cb31a830112fa81944c29e2641f160b773f38 Mon Sep 17 00:00:00 2001 From: Diego Carvallo Date: Tue, 18 Nov 2025 23:14:58 +0000 Subject: [PATCH 2/6] feat: add id field to readme and json schema --- docs/README.md | 49 +++++++++++++++++++++++++++++ schema/odcs-json-schema-v3.1.0.json | 35 +++++++++++++++++++++ 2 files changed, 84 insertions(+) diff --git a/docs/README.md b/docs/README.md index e2a7517..47fc5f0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -219,6 +219,7 @@ schema: | Key | UX label | Required | Description | |--------------------------|------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| id | ID | No | Stable technical identifier for references. See [ID Field for Stable References](#id-field-for-stable-references) for details. | | name | Name | Yes | Name of the element. | | physicalName | Physical Name | No | Physical name. | | description | Description | No | Description of the element. | @@ -228,6 +229,54 @@ schema: | tags | Tags | No | A list of tags that may be assigned to the elements (object or property); the tags keyword may appear at any level. Tags may be used to better categorize an element. For example, `finance`, `sensitive`, `employee_record`. | | customProperties | Custom Properties | No | Custom properties that are not part of the standard. | +#### ID Field for Stable References + +The `id` field provides stable technical identifiers that enable references resilient to array reordering and consistency across the standard. + +**Rules:** +- Optional everywhere it is allowed +- Must be unique within its containing array/object collection +- Should remain stable across versions and refactors to preserve referential integrity +- Cannot contain any special characters ('-', '_' allowed): e.g `.`, `#`, `/`, `\`, `@`, `!`, `%`, `&`, `^` + +**Where `id` is Allowed:** +- Contract-level repeated blocks: `schema` objects, `servers` items, `roles` items, `support` items, `slaProperties` items, `quality` items, `customProperties` items +- Schema structures: Objects (tables) and Properties (columns) + +**Semantic Guidance:** + +| Field | Purpose | Example | +|-------|---------|---------| +| `id` | Stable technical identifier for references | `customers_tbl` | +| `name` | Logical name (required primary key) | `customers` | +| `businessName` | Business-facing display name | `Customer Data` | +| `physicalName` | Physical implementation name | `dim_customers` | + +**Example with all naming fields:** + +```yaml +schema: + - id: customers_tbl # Stable identifier for references + name: customers # Logical name (required) + businessName: Customer Data # Business-facing display name + physicalName: dim_customers # Physical implementation name + physicalType: table + properties: + - id: cust_id_pk # Stable identifier for property + name: customer_id + primaryKey: true + logicalType: integer + - id: cust_email + name: email + logicalType: string + quality: + - id: dq_email_format # Stable identifier for quality rule + metric: pattern + arguments: + regex: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' + mustBe: 0 +``` + #### Applicable to Objects | Key | UX label | Required | Description | diff --git a/schema/odcs-json-schema-v3.1.0.json b/schema/odcs-json-schema-v3.1.0.json index bde9d83..b964bd9 100644 --- a/schema/odcs-json-schema-v3.1.0.json +++ b/schema/odcs-json-schema-v3.1.0.json @@ -137,6 +137,11 @@ "type": "object", "description": "Data source details of where data is physically stored.", "properties": { + "id": { + "type": "string", + "description": "Stable technical identifier for references. Must be unique within its containing array. Cannot contain special characters ('-', '_' allowed): . # / \\ @ ! % & ^", + "pattern": "^[^.#/\\\\@!%&^]+$" + }, "server": { "type": "string", "description": "Identifier of the server." @@ -1500,6 +1505,11 @@ "SchemaElement": { "type": "object", "properties": { + "id": { + "type": "string", + "description": "Stable technical identifier for references. Must be unique within its containing array. Cannot contain special characters ('-', '_' allowed): . # / \\ @ ! % & ^", + "pattern": "^[^.#/\\\\@!%&^]+$" + }, "name": { "type": "string", "description": "Name of the element." @@ -2030,6 +2040,11 @@ "DataQuality": { "type": "object", "properties": { + "id": { + "type": "string", + "description": "Stable technical identifier for references. Must be unique within its containing array. Cannot contain special characters ('-', '_' allowed): . # / \\ @ ! % & ^", + "pattern": "^[^.#/\\\\@!%&^]+$" + }, "authoritativeDefinitions": { "$ref": "#/$defs/AuthoritativeDefinitions" }, @@ -2338,6 +2353,11 @@ "SupportItem": { "type": "object", "properties": { + "id": { + "type": "string", + "description": "Stable technical identifier for references. Must be unique within its containing array. Cannot contain special characters ('-', '_' allowed): . # / \\ @ ! % & ^", + "pattern": "^[^.#/\\\\@!%&^]+$" + }, "channel": { "type": "string", "description": "Channel name or identifier." @@ -2478,6 +2498,11 @@ "Role": { "type": "object", "properties": { + "id": { + "type": "string", + "description": "Stable technical identifier for references. Must be unique within its containing array. Cannot contain special characters ('-', '_' allowed): . # / \\ @ ! % & ^", + "pattern": "^[^.#/\\\\@!%&^]+$" + }, "role": { "type": "string", "description": "Name of the IAM role that provides access to the dataset." @@ -2508,6 +2533,11 @@ "ServiceLevelAgreementProperty": { "type": "object", "properties": { + "id": { + "type": "string", + "description": "Stable technical identifier for references. Must be unique within its containing array. Cannot contain special characters ('-', '_' allowed): . # / \\ @ ! % & ^", + "pattern": "^[^.#/\\\\@!%&^]+$" + }, "property": { "type": "string", "description": "Specific property in SLA, check the periodic table. May requires units (more details to come)." @@ -2578,6 +2608,11 @@ "CustomProperty": { "type": "object", "properties": { + "id": { + "type": "string", + "description": "Stable technical identifier for references. Must be unique within its containing array. Cannot contain special characters ('-', '_' allowed): . # / \\ @ ! % & ^", + "pattern": "^[^.#/\\\\@!%&^]+$" + }, "property": { "type": "string", "description": "The name of the key. Names should be in camel case–the same as if they were permanent properties in the contract." From f2424b6ba4930480b3591d9f6b204f5683e9418e Mon Sep 17 00:00:00 2001 From: Diego Carvallo Date: Wed, 19 Nov 2025 10:12:33 +0000 Subject: [PATCH 3/6] refactor(stable_id): centralize stable id --- schema/odcs-json-schema-v3.1.0.json | 33 +++++++++++------------------ 1 file changed, 12 insertions(+), 21 deletions(-) diff --git a/schema/odcs-json-schema-v3.1.0.json b/schema/odcs-json-schema-v3.1.0.json index b964bd9..cca4e0f 100644 --- a/schema/odcs-json-schema-v3.1.0.json +++ b/schema/odcs-json-schema-v3.1.0.json @@ -133,14 +133,17 @@ "additionalProperties": false, "unevaluatedProperties": false, "$defs": { + "StableId": { + "type": "string", + "description": "Stable technical identifier for references. Must be unique within its containing array. Cannot contain special characters ('-', '_' allowed): . # / \\ @ ! % & ^", + "pattern": "^[^.#/\\\\@!%&^]+$" + }, "Server": { "type": "object", "description": "Data source details of where data is physically stored.", "properties": { "id": { - "type": "string", - "description": "Stable technical identifier for references. Must be unique within its containing array. Cannot contain special characters ('-', '_' allowed): . # / \\ @ ! % & ^", - "pattern": "^[^.#/\\\\@!%&^]+$" + "$ref": "#/$defs/StableId" }, "server": { "type": "string", @@ -1506,9 +1509,7 @@ "type": "object", "properties": { "id": { - "type": "string", - "description": "Stable technical identifier for references. Must be unique within its containing array. Cannot contain special characters ('-', '_' allowed): . # / \\ @ ! % & ^", - "pattern": "^[^.#/\\\\@!%&^]+$" + "$ref": "#/$defs/StableId" }, "name": { "type": "string", @@ -2041,9 +2042,7 @@ "type": "object", "properties": { "id": { - "type": "string", - "description": "Stable technical identifier for references. Must be unique within its containing array. Cannot contain special characters ('-', '_' allowed): . # / \\ @ ! % & ^", - "pattern": "^[^.#/\\\\@!%&^]+$" + "$ref": "#/$defs/StableId" }, "authoritativeDefinitions": { "$ref": "#/$defs/AuthoritativeDefinitions" @@ -2354,9 +2353,7 @@ "type": "object", "properties": { "id": { - "type": "string", - "description": "Stable technical identifier for references. Must be unique within its containing array. Cannot contain special characters ('-', '_' allowed): . # / \\ @ ! % & ^", - "pattern": "^[^.#/\\\\@!%&^]+$" + "$ref": "#/$defs/StableId" }, "channel": { "type": "string", @@ -2499,9 +2496,7 @@ "type": "object", "properties": { "id": { - "type": "string", - "description": "Stable technical identifier for references. Must be unique within its containing array. Cannot contain special characters ('-', '_' allowed): . # / \\ @ ! % & ^", - "pattern": "^[^.#/\\\\@!%&^]+$" + "$ref": "#/$defs/StableId" }, "role": { "type": "string", @@ -2534,9 +2529,7 @@ "type": "object", "properties": { "id": { - "type": "string", - "description": "Stable technical identifier for references. Must be unique within its containing array. Cannot contain special characters ('-', '_' allowed): . # / \\ @ ! % & ^", - "pattern": "^[^.#/\\\\@!%&^]+$" + "$ref": "#/$defs/StableId" }, "property": { "type": "string", @@ -2609,9 +2602,7 @@ "type": "object", "properties": { "id": { - "type": "string", - "description": "Stable technical identifier for references. Must be unique within its containing array. Cannot contain special characters ('-', '_' allowed): . # / \\ @ ! % & ^", - "pattern": "^[^.#/\\\\@!%&^]+$" + "$ref": "#/$defs/StableId" }, "property": { "type": "string", From 99ac012ee2d7ac0f03faafc0427e87fe92f48b45 Mon Sep 17 00:00:00 2001 From: Diego Carvallo Date: Wed, 19 Nov 2025 10:31:47 +0000 Subject: [PATCH 4/6] fix(relationships): add regex for reference blocks in json schema --- schema/odcs-json-schema-v3.1.0.json | 34 ++++++++++++++++++++++++----- 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/schema/odcs-json-schema-v3.1.0.json b/schema/odcs-json-schema-v3.1.0.json index bde9d83..99dea8d 100644 --- a/schema/odcs-json-schema-v3.1.0.json +++ b/schema/odcs-json-schema-v3.1.0.json @@ -133,6 +133,16 @@ "additionalProperties": false, "unevaluatedProperties": false, "$defs": { + "ShorthandReference": { + "type": "string", + "description": "Shorthand notation using name fields (table_name.column_name)", + "pattern": "^[A-Za-z_][A-Za-z0-9_]*\\.[A-Za-z_][A-Za-z0-9_]*$" + }, + "FullyQualifiedReference": { + "type": "string", + "description": "Fully qualified notation using id fields (section/id/properties/id), optionally prefixed with external file reference", + "pattern": "^(?:(?:https?:\\/\\/)?[A-Za-z0-9._\\-\\/]+\\.yaml#)?\\/?[A-Za-z_][A-Za-z0-9_]*\\/[A-Za-z0-9_-]+(?:\\/[A-Za-z_][A-Za-z0-9_]*\\/[A-Za-z0-9_-]+)*$" + }, "Server": { "type": "object", "description": "Data source details of where data is physically stored.", @@ -2651,14 +2661,20 @@ "from": { "oneOf": [ { - "type": "string", - "description": "Source property reference using fully qualified notation (schema//properties/) or shorthand notation (table_name.column_name)." + "anyOf": [ + { "$ref": "#/$defs/ShorthandReference" }, + { "$ref": "#/$defs/FullyQualifiedReference" } + ], + "description": "Source property reference using fully qualified or shorthand notation." }, { "type": "array", "description": "Array of source properties for composite keys.", "items": { - "type": "string" + "anyOf": [ + { "$ref": "#/$defs/ShorthandReference" }, + { "$ref": "#/$defs/FullyQualifiedReference" } + ] }, "minItems": 1 } @@ -2668,14 +2684,20 @@ "to": { "oneOf": [ { - "type": "string", - "description": "Target property reference using fully qualified notation (schema//properties/) or shorthand notation (table_name.column_name)." + "anyOf": [ + { "$ref": "#/$defs/ShorthandReference" }, + { "$ref": "#/$defs/FullyQualifiedReference" } + ], + "description": "Target property reference using fully qualified or shorthand notation." }, { "type": "array", "description": "Array of target properties for composite keys.", "items": { - "type": "string" + "anyOf": [ + { "$ref": "#/$defs/ShorthandReference" }, + { "$ref": "#/$defs/FullyQualifiedReference" } + ] }, "minItems": 1 } From b116fd1c0232601bb7908d957f68e5562704524a Mon Sep 17 00:00:00 2001 From: Diego Carvallo Date: Wed, 19 Nov 2025 10:46:00 +0000 Subject: [PATCH 5/6] refactor: centralise stable id and update regex --- docs/README.md | 2 +- schema/odcs-json-schema-v3.1.0.json | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/README.md b/docs/README.md index d313bd9..0b32108 100644 --- a/docs/README.md +++ b/docs/README.md @@ -237,7 +237,7 @@ The `id` field provides stable technical identifiers that enable references resi - Optional everywhere it is allowed - Must be unique within its containing array/object collection - Should remain stable across versions and refactors to preserve referential integrity -- Cannot contain any special characters ('-', '_' allowed): e.g `.`, `#`, `/`, `\`, `@`, `!`, `%`, `&`, `^` +- Cannot contain any special characters ('-', '_' allowed). **Where `id` is Allowed:** - Contract-level repeated blocks: `schema` objects, `servers` items, `roles` items, `support` items, `slaProperties` items, `quality` items, `customProperties` items diff --git a/schema/odcs-json-schema-v3.1.0.json b/schema/odcs-json-schema-v3.1.0.json index 8aa939a..bfea083 100644 --- a/schema/odcs-json-schema-v3.1.0.json +++ b/schema/odcs-json-schema-v3.1.0.json @@ -133,11 +133,6 @@ "additionalProperties": false, "unevaluatedProperties": false, "$defs": { - "StableId": { - "type": "string", - "description": "Stable technical identifier for references. Must be unique within its containing array. Cannot contain special characters ('-', '_' allowed): . # / \\ @ ! % & ^", - "pattern": "^[^.#/\\\\@!%&^]+$" - }, "ShorthandReference": { "type": "string", "description": "Shorthand notation using name fields (table_name.column_name)", @@ -148,6 +143,11 @@ "description": "Fully qualified notation using id fields (section/id/properties/id), optionally prefixed with external file reference", "pattern": "^(?:(?:https?:\\/\\/)?[A-Za-z0-9._\\-\\/]+\\.yaml#)?\\/?[A-Za-z_][A-Za-z0-9_]*\\/[A-Za-z0-9_-]+(?:\\/[A-Za-z_][A-Za-z0-9_]*\\/[A-Za-z0-9_-]+)*$" }, + "StableId": { + "type": "string", + "description": "Stable technical identifier for references. Must be unique within its containing array. Cannot contain special characters ('-', '_' allowed).", + "pattern": "^[A-Za-z0-9_-]+$" + }, "Server": { "type": "object", "description": "Data source details of where data is physically stored.", From cf54ce003f69d9c3e446c510d9172f65f9a00f58 Mon Sep 17 00:00:00 2001 From: Diego Carvallo Date: Wed, 19 Nov 2025 16:55:48 +0000 Subject: [PATCH 6/6] feat: add changelong --- CHANGELOG.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0977b7e..096ea42 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,13 +13,15 @@ This document tracks the history and evolution of the **Open Data Contract Stand * Support for property-level relationships where `from` field is implicit. * Support for schema-level relationships with explicit `from` and `to` fields. * Support for composite foreign keys using arrays in `from` and `to` fields. - * Support for nested property references using dot notation (e.g., `accounts.address.street`). + * Support for nested property references using dot shorthand notation (e.g., `accounts.address_street`). + * Support for nested property references using fully qualified references (e.g `/schema/schema_id/properties/my_property`) * Add `customProperties` to relationships for metadata like cardinality, labels, and descriptions. * New `Relationship` definition in JSON schema with fields: * `type`: Type of relationship (defaults to `foreignKey`) * `from`: Source property reference (optional at property level) * `to`: Target property reference (required) * `customProperties`: Additional metadata +* **Adds** `id` field across the schema for direct object and property identification * **Breaking change** to schema: * Alter `exclusiveMaximum` and `exclusiveMinimum` for `integer/number` logical data type to be `number` instead of `boolean`. [Conforms with JSON Schema specification](https://json-schema.org/understanding-json-schema/reference/numeric#range). * Alter `exclusiveMaximum` and `exclusiveMinimum` for `date` logical data type to be `string` instead of `boolean`.