From 045398fb9507f94700c714152074eb888fceb939 Mon Sep 17 00:00:00 2001 From: Fabian Steeg Date: Tue, 11 Mar 2025 15:03:34 +0100 Subject: [PATCH 1/3] Extract `lang` & `dir` schema definitions, reuse via `$ref` (#138) --- 1.0-draft/schemas/data-extension-response.json | 8 ++++---- 1.0-draft/schemas/dir.json | 10 ++++++++++ 1.0-draft/schemas/lang.json | 5 +++++ 1.0-draft/schemas/reconciliation-query-batch.json | 6 ++++-- 4 files changed, 23 insertions(+), 6 deletions(-) create mode 100644 1.0-draft/schemas/dir.json create mode 100644 1.0-draft/schemas/lang.json diff --git a/1.0-draft/schemas/data-extension-response.json b/1.0-draft/schemas/data-extension-response.json index 22e9db7..18c4b1e 100644 --- a/1.0-draft/schemas/data-extension-response.json +++ b/1.0-draft/schemas/data-extension-response.json @@ -81,10 +81,10 @@ "type": "string" }, "lang": { - "type": "string" + "$ref": "lang.json" }, "dir": { - "type": "string" + "$ref": "dir.json" } }, "required": [ @@ -100,10 +100,10 @@ "type": "string" }, "lang": { - "type": "string" + "$ref": "lang.json" }, "dir": { - "type": "string" + "$ref": "dir.json" } }, "required": [ diff --git a/1.0-draft/schemas/dir.json b/1.0-draft/schemas/dir.json new file mode 100644 index 0000000..137f4c5 --- /dev/null +++ b/1.0-draft/schemas/dir.json @@ -0,0 +1,10 @@ +{ + "$id": "https://reconciliation-api.github.io/specs/draft/schemas/dir.json", + "type": "string", + "enum": [ + "ltr", + "rtl", + "auto" + ], + "description": "The text direction for the natural language fields of this object" +} diff --git a/1.0-draft/schemas/lang.json b/1.0-draft/schemas/lang.json new file mode 100644 index 0000000..0ae6761 --- /dev/null +++ b/1.0-draft/schemas/lang.json @@ -0,0 +1,5 @@ +{ + "$id": "https://reconciliation-api.github.io/specs/draft/schemas/lang.json", + "type": "string", + "description": "The text-processing language for the natural language fields of this object" +} diff --git a/1.0-draft/schemas/reconciliation-query-batch.json b/1.0-draft/schemas/reconciliation-query-batch.json index ad8c7a8..c346088 100644 --- a/1.0-draft/schemas/reconciliation-query-batch.json +++ b/1.0-draft/schemas/reconciliation-query-batch.json @@ -52,8 +52,10 @@ "description": "The maximum number of candidates to return" }, "lang": { - "type": "string", - "description": "The text-processing language for the query" + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" }, "conditions": { "type": "array", From a3ea0d16a27ce03ca50f7522d5fed3da68ee0459 Mon Sep 17 00:00:00 2001 From: Fabian Steeg Date: Tue, 11 Mar 2025 16:22:44 +0100 Subject: [PATCH 2/3] Add `lang` & `dir` to all relevant schemas (#138) i.e. to objects with natural language fields, see spec 8.2 & 8.3 --- .../data-extension-property-proposal.json | 6 ++++ .../schemas/data-extension-response.json | 12 +++++++ 1.0-draft/schemas/manifest.json | 36 +++++++++++++++++++ .../schemas/reconciliation-query-batch.json | 6 ++++ .../schemas/reconciliation-result-batch.json | 18 ++++++++++ .../schemas/suggest-entities-response.json | 12 +++++++ .../schemas/suggest-properties-response.json | 12 +++++++ 1.0-draft/schemas/type.json | 6 ++++ 8 files changed, 108 insertions(+) diff --git a/1.0-draft/schemas/data-extension-property-proposal.json b/1.0-draft/schemas/data-extension-property-proposal.json index 3aa2f00..ae785b6 100644 --- a/1.0-draft/schemas/data-extension-property-proposal.json +++ b/1.0-draft/schemas/data-extension-property-proposal.json @@ -20,6 +20,12 @@ "description": { "type": "string", "description": "An optional description which can be provided to disambiguate namesakes, providing more context." + }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" } }, "required": [ diff --git a/1.0-draft/schemas/data-extension-response.json b/1.0-draft/schemas/data-extension-response.json index 18c4b1e..1850517 100644 --- a/1.0-draft/schemas/data-extension-response.json +++ b/1.0-draft/schemas/data-extension-response.json @@ -15,6 +15,12 @@ "name": { "type": "string" }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" + }, "type": { "type": "object", "properties": { @@ -23,6 +29,12 @@ }, "name": { "type": "string" + }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" } }, "required": [ diff --git a/1.0-draft/schemas/manifest.json b/1.0-draft/schemas/manifest.json index b63036a..8560039 100644 --- a/1.0-draft/schemas/manifest.json +++ b/1.0-draft/schemas/manifest.json @@ -18,6 +18,12 @@ "type": "string", "description": "A human-readable name for the service or data source" }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" + }, "documentation": { "type": "string", "description": "A URI which hosts documentation about this service" @@ -136,6 +142,12 @@ }, "helpText": { "type": "string" + }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" } }, "required": [ @@ -165,6 +177,12 @@ }, "helpText": { "type": "string" + }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" } }, "required": [ @@ -194,6 +212,12 @@ }, "helpText": { "type": "string" + }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" } }, "required": [ @@ -224,6 +248,12 @@ "helpText": { "type": "string" }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" + }, "choices": { "type": "array", "items": { @@ -234,6 +264,12 @@ }, "name": { "type": "string" + }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" } }, "required": [ diff --git a/1.0-draft/schemas/reconciliation-query-batch.json b/1.0-draft/schemas/reconciliation-query-batch.json index c346088..d5ed744 100644 --- a/1.0-draft/schemas/reconciliation-query-batch.json +++ b/1.0-draft/schemas/reconciliation-query-batch.json @@ -24,6 +24,12 @@ }, "name": { "type": "string" + }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" } }, "required": [ diff --git a/1.0-draft/schemas/reconciliation-result-batch.json b/1.0-draft/schemas/reconciliation-result-batch.json index dd023fe..5887aa6 100644 --- a/1.0-draft/schemas/reconciliation-result-batch.json +++ b/1.0-draft/schemas/reconciliation-result-batch.json @@ -30,6 +30,12 @@ "type": "string", "description": "Optional description of the candidate entity" }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" + }, "score": { "type": "number", "description": "Number indicating how likely it is that the candidate matches the query" @@ -48,6 +54,12 @@ "type": "string", "description": "A human-readable name for the feature" }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" + }, "value": { "description": "The value of the feature for this reconciliation candidate", "oneOf": [ @@ -85,6 +97,12 @@ }, "name": { "type": "string" + }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" } }, "required": [ diff --git a/1.0-draft/schemas/suggest-entities-response.json b/1.0-draft/schemas/suggest-entities-response.json index 3b467ff..56c4c6f 100644 --- a/1.0-draft/schemas/suggest-entities-response.json +++ b/1.0-draft/schemas/suggest-entities-response.json @@ -21,6 +21,12 @@ "type": "string", "description": "An optional description which can be provided to disambiguate namesakes, providing more context." }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" + }, "notable": { "type": "array", "description": "Types the suggest entity belongs to", @@ -35,6 +41,12 @@ }, "name": { "type": "string" + }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" } }, "required": [ diff --git a/1.0-draft/schemas/suggest-properties-response.json b/1.0-draft/schemas/suggest-properties-response.json index 2e02b01..9ee435a 100644 --- a/1.0-draft/schemas/suggest-properties-response.json +++ b/1.0-draft/schemas/suggest-properties-response.json @@ -21,6 +21,12 @@ "type": "string", "description": "An optional description which can be provided to disambiguate namesakes, providing more context." }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" + }, "matchQualifiers": { "type": "array", "description": "An optional array of objects representing the matchQualifiers supported for the suggested property", @@ -34,6 +40,12 @@ "name": { "type": "string", "description": "Name of the matchQualifier" + }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" } }, "required": [ diff --git a/1.0-draft/schemas/type.json b/1.0-draft/schemas/type.json index b4e192e..26754d5 100644 --- a/1.0-draft/schemas/type.json +++ b/1.0-draft/schemas/type.json @@ -14,6 +14,12 @@ "type": "string", "description": "An optional description which can be provided to disambiguate namesakes, providing more context." }, + "lang": { + "$ref": "lang.json" + }, + "dir": { + "$ref": "dir.json" + }, "broader": { "type": "array", "description": "An optional array of types, each representing a direct (i.e., immediate) broader category of entities.", From 8b8282d7316a3ba50c9b091d06a833cb8137e235 Mon Sep 17 00:00:00 2001 From: Fabian Steeg Date: Tue, 11 Mar 2025 16:39:34 +0100 Subject: [PATCH 3/3] Add `helpText` to natural language fields in 8.2 & 8.3 (#138) --- 1.0-draft/index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/1.0-draft/index.html b/1.0-draft/index.html index 0fac1b6..68e4032 100644 --- a/1.0-draft/index.html +++ b/1.0-draft/index.html @@ -961,7 +961,7 @@

Text-processing language

All objects used in this protocol (entities, types, properties, queries, candidates, features, etc.) MAY declare an explicit text-processing language in a lang field. The lang value MUST be a single valid (i.e. found in the [[IANA Language Subtag Registry]]) [[BCP 47]] language tag. This text-processing language applies to the natural language fields of the object: name, description, - query (for reconciliation queries), v and str (for property values). Nested objects inherit the text-processing language of their parent, and can override it by setting their own lang value + query (for reconciliation queries), v and str (for property values), helpText (for data extension property settings). Nested objects inherit the text-processing language of their parent, and can override it by setting their own lang value (see example below). A default text-processing language for any natural language string returned or processed by a service MAY be set in the lang field of the service manifest. Client and service implementors SHOULD consider the text-processing language to ensure correct processing of natural language content.

@@ -977,7 +977,7 @@

Text direction

All objects returned by reconciliation services (entities, types, properties, candidates, features, etc.) MAY declare an explicit text base direction in a dir field. The dir value MUST be ltr for left-to-right, rtl for right-to-left, or auto for determining the direction by examining the content of each JSON field. - This base direction applies to the natural language fields of the object: name and description (for candidates etc.), v and str (for property values). + This base direction applies to the natural language fields of the object: name and description (for candidates etc.), v and str (for property values), helpText (for data extension property settings). Nested objects inherit the base direction of their parent, and can override it by setting their own dir value. A default base direction for any natural language string returned or processed by a service MAY be set in the dir field of the service manifest. If no explicit base direction is given, left-to-right is considered the default base direction. Clients SHOULD consider the base direction to ensure correct rendering of content, e.g. by setting corresponding dir attributes when rendering JSON responses in HTML. For instance, rendering a Persian label for 'Yahoo!' like یاهو! right-to-left will correctly display as یاهو!.