Merge pull request #1149 from finos/clarify_identifier_values_should_be_strings

Identifier values should be of type string

Author: kriswest

CHANGELOG.md

@@ -8,6 +8,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 
+* Added clarification that `id` field values SHOULD always be strings to context schema definition (a restriction that can't easily be represented in the generated types). ([#1149](https://github.com/finos/FDC3/pull/1149))
+
 ### Changed
 
 ### Deprecated

docs/context/ref/Context.md

@@ -54,11 +54,12 @@ derived types may require the name object as mandatory, depending on use case.
 
 ### `id` (optional)
 
-Context data objects may include a set of equivalent key-value pairs that can be used to help applications
-identify and look up the context type they receive in their own domain. The idea behind this design is that applications can provide as many equivalent identifiers to a target application as possible, e.g. an instrument may be represented by an ISIN, CUSIP or Bloomberg identifier.
+Context data objects may include a set of equivalent key-value pairs that can be used to help applications identify and look up the context type they receive in their own domain. The idea behind this design is that applications can provide as many equivalent identifiers to a target application as possible, e.g. an instrument may be represented by an ISIN, CUSIP or Bloomberg identifier.
 
 Identifiers do not make sense for all types of data, so the `id` property is therefore optional, but some derived types may choose to require at least one identifier.
 
+Identifier values SHOULD always be of type string.
+
 ## See Also
 
 FDC3 Specifications

docs/context/spec.md

@@ -110,6 +110,8 @@ An `id` field with type `object` is defined in the base [fdc3.context](ref/Conte
 
 Where an identifier is the name of an existing standard, external to FDC3, it is represented in all caps. For example: FIGI, PERMID, CUSIP, ISO-2. When an identifier is a more general concept, it is represented in all lower case.  For example: ticker, name, geocode, email.
 
+Identifier values SHOULD always be of type string.
+
 All standard identifier names are reserved names. Applications may use their own identifiers ad hoc. For example:
 
 ```json

schemas/context/context.schema.json

@@ -25,9 +25,7 @@
         },
         "id": {
           "type": "object",
-          "unevaluatedProperties": {
-            "type": "string"
-          }
+          "unevaluatedProperties": {"type": "string" }
         }
       },
       "additionalProperties": true,
@@ -52,10 +50,8 @@
         "id": {
           "type": "object",
           "title": "Id",
-          "description": "Context data objects may include a set of equivalent key-value pairs that can be used to help applications identify and look up the context type they receive in their own domain. The idea behind this design is that applications can provide as many equivalent identifiers to a target application as possible, e.g. an instrument may be represented by an ISIN, CUSIP or Bloomberg identifier.\n\nIdentifiers do not make sense for all types of data, so the `id` property is therefore optional, but some derived types may choose to require at least one identifier.",
-          "unevaluatedProperties": {
-            "type": "string"
-          }
+          "description": "Context data objects may include a set of equivalent key-value pairs that can be used to help applications identify and look up the context type they receive in their own domain. The idea behind this design is that applications can provide as many equivalent identifiers to a target application as possible, e.g. an instrument may be represented by an ISIN, CUSIP or Bloomberg identifier.\n\nIdentifiers do not make sense for all types of data, so the `id` property is therefore optional, but some derived types may choose to require at least one identifier. Identifier values SHOULD always be of type string.",
+          "unevaluatedProperties": {"type": "string" }
         }
       },
       "additionalProperties": true,

src/bridging/BridgingTypes.ts

@@ -669,6 +669,7 @@ export interface ContextElement {
    *
    * Identifiers do not make sense for all types of data, so the `id` property is therefore
    * optional, but some derived types may choose to require at least one identifier.
+   * Identifier values SHOULD always be of type string.
    */
   id?: { [key: string]: any };
   /**
@@ -3102,7 +3103,7 @@ export interface PrivateChannelEventListenerAddedAgentRequestMeta {
  */
 export interface PrivateChannelEventListenerAddedAgentRequestPayload {
   /**
-   * The id of the PrivateChannel that the event listener was added to
+   * The id of the PrivateChannel that the event listener was added to.
    */
   channelId: string;
   listenerType: PrivateChannelEventListenerTypes;
@@ -3165,7 +3166,7 @@ export interface PrivateChannelEventListenerAddedBridgeRequestMeta {
  */
 export interface PrivateChannelEventListenerAddedBridgeRequestPayload {
   /**
-   * The id of the PrivateChannel that the event listener was added to
+   * The id of the PrivateChannel that the event listener was added to.
    */
   channelId: string;
   listenerType: PrivateChannelEventListenerTypes;
@@ -3213,7 +3214,7 @@ export interface PrivateChannelEventListenerRemovedAgentRequestMeta {
  */
 export interface PrivateChannelEventListenerRemovedAgentRequestPayload {
   /**
-   * The id of the PrivateChannel that the event listener was removed from
+   * The id of the PrivateChannel that the event listener was removed from.
    */
   channelId: string;
   listenerType: PrivateChannelEventListenerTypes;
@@ -3271,7 +3272,7 @@ export interface PrivateChannelEventListenerRemovedBridgeRequestMeta {
  */
 export interface PrivateChannelEventListenerRemovedBridgeRequestPayload {
   /**
-   * The id of the PrivateChannel that the event listener was removed from
+   * The id of the PrivateChannel that the event listener was removed from.
    */
   channelId: string;
   listenerType: PrivateChannelEventListenerTypes;
@@ -4178,6 +4179,7 @@ export interface Context {
    *
    * Identifiers do not make sense for all types of data, so the `id` property is therefore
    * optional, but some derived types may choose to require at least one identifier.
+   * Identifier values SHOULD always be of type string.
    */
   id?: { [key: string]: any };
   /**

src/context/ContextTypes.ts

@@ -129,6 +129,7 @@ export interface ContextElement {
    *
    * Identifiers do not make sense for all types of data, so the `id` property is therefore
    * optional, but some derived types may choose to require at least one identifier.
+   * Identifier values SHOULD always be of type string.
    */
   id?: { [key: string]: any };
   /**
@@ -946,6 +947,7 @@ export interface Context {
    *
    * Identifiers do not make sense for all types of data, so the `id` property is therefore
    * optional, but some derived types may choose to require at least one identifier.
+   * Identifier values SHOULD always be of type string.
    */
   id?: { [key: string]: any };
   /**