From 743c24fc56bb868b0dae1d8b6e7c93dd99c6fe07 Mon Sep 17 00:00:00 2001 From: Eric Pugh Date: Sat, 31 Aug 2024 08:48:08 -0400 Subject: [PATCH] restore 1.0.0 version of spec from tagged release --- schema/1.0.0/event.schema.json | 167 ++++++++++++++++++++++++ schema/1.0.0/query.request.schema.json | 46 +++++++ schema/1.0.0/query.response.schema.json | 25 ++++ 3 files changed, 238 insertions(+) create mode 100644 schema/1.0.0/event.schema.json create mode 100644 schema/1.0.0/query.request.schema.json create mode 100644 schema/1.0.0/query.response.schema.json diff --git a/schema/1.0.0/event.schema.json b/schema/1.0.0/event.schema.json new file mode 100644 index 0000000..e111c98 --- /dev/null +++ b/schema/1.0.0/event.schema.json @@ -0,0 +1,167 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://o19s.github.io/ubi/schema/1.0.0/event.schema.json", + "title": "Event tracking for UBI", + "description": "Version 1.0.0; last updated 2024-06-14. An event that occurred, typically in response to a user.", + "type": "object", + "required": ["action_name", "query_id", "timestamp"], + "properties": { + "application": { + "description": "name of the application tracking UBI events.", + "type": "string", + "maxLength": 100, + "examples": [ + "amazon-shop", + "ABC-microservice", + "doctor-search" + ] + }, + "action_name": { + "description": "The name of the action that triggered the event. We have a set of common defaults, however you can pass in whatever you want.", + "oneOf": [ + { + "type": "string", + "maxLength": 100, + "enum": ["click_through", "add_to_cart", "click", "watch", "view", "purchase"] + }, + { + "type": "string", + "maxLength": 100 + } + ] + }, + "query_id": { + "description": "The unique identifier of a query, typically a UUID, but can be any string.", + "oneOf": [ + { + "type": "string", + "format": "uuid", + "examples": ["00112233-4455-6677-8899-aabbccddeeff"] + }, + { + "type": "string", + "maxLength": 100, + "examples": ["1234-user-5678"] + } + ] + }, + "client_id": { + "description": "The client issuing the query. This could be a unique browser, a microservice that performs searches, a crawling bot.", + "type": "string", + "maxLength": 100, + "examples": ["5e3b2a1c-8b7d-4f2e-a3d4-c9b2e1f3a4b5","quepid-nightly-bot", "BugsBunny::Firefox@0967084"] + }, + "timestamp": { + "description": "When the event took place.", + "type": "string", + "format": "date-time", + "examples": ["2018-11-13T20:20:39+00:00"] + }, + "message_type": { + "description": "Group various `action_name`'s into logical bins.", + "type": "string", + "maxLength": 100, + "examples": ["QUERY", "CONVERSION"], + "$comment": "TDB: action_type? event_type? Should the front end even define this?" + }, + "message": { + "description": "Optional text message for the log entry. For example, for a message_type of QUERY, we would expect the text to be about what the user is searching on.", + "type": "string", + "maxLength": 1024 + }, + "event_attributes": { + "description": "Extensible details about a specific event.", + "type": "object", + "additionalProperties": true, + "required": ["position"], + "properties": { + "object": { + "description": "Structure which contains identifying information of the object returned from the query that the user interacts with (i.e.: a book, a product, a post, etc..).", + "type": "object", + "additionalProperties": true, + "required": ["object_id"], + "properties": { + "object_id": { + "description": "The id that a user could look up and find the object instance within the *document corpus*. Examples include: _ssn_, _isbn_, _ean_, etc. Variants need to be incorporated in the `object_id`, so for a t-shirt that is red, you would need SKU level as the `object_id`.", + "examples": ["XYZ-12345", "ISBN 0-061-96436-0", "123"], + "anyOf": [ + { + "type": "string", + "maxLength": 256 + }, + { + "type": "integer" + } + ] + }, + "object_id_field":{ + "description": "The name of the field that has the id of the objects that will be stored in the backend queries data store. So it you have a query for products and want to save the SKUs, then this might be `sku` and if you are querying for people, maybe this is `ssn`. If you do not provide this value then the default primary identifier in your search index will be used. For example `_id` on OpenSearch. ", + "type": "string", + "maxLength": 100 + }, + "internal_id": { + "description": "A unique id that the an individual search engine uses internally to index the object via. For example, in OpenSearch, think the `_id` field in the indices.", + "examples": ["1", "123456"], + "anyOf": [ + { + "type": "string", + "maxLength": 256 + }, + { + "type": "integer" + } + ] + } + } + }, + "position": { + "description": "Structure that contains information on the location of the event origin, such as screen x,y coordinates, or the nth object out of 10 results.", + "type": "object", + "additionalProperties": true, + "oneOf": [ + { + "type": "object", + "properties": { + "ordinal": { + "description": "The nth position of the document on the search results page.", + "type": "object", + "properties": { + "index": { + "description": "The position of the document. For grid layout this would be left to right, ignoring wrapping.", + "type": "integer", + "examples": [1, 3, 24] + } + }, + "required": ["index"] + } + }, + "required": ["ordinal"] + }, + { + "type": "object", + "properties": { + "xy": { + "description": "The x,y coordinates on the screen for triggering an event.", + "$comment": "What about bounding boxes?", + "type": "object", + "properties": { + "x": { + "description": "The horizontal location on the page or screen of the event.", + "type": "number" + }, + "y": { + "description": "The vertical location on the page or screen of the event.", + "type": "number" + } + }, + "required": ["x", "y"] + } + }, + "required": ["xy"] + } + ] + } + } + } + } +} diff --git a/schema/1.0.0/query.request.schema.json b/schema/1.0.0/query.request.schema.json new file mode 100644 index 0000000..a8876d6 --- /dev/null +++ b/schema/1.0.0/query.request.schema.json @@ -0,0 +1,46 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://o19s.github.io/ubi/schema/1.0.0/query.request.schema.json", + "title": "Query Tracking for UBI", + "description": "Version 1.0.0; last updated 2024-06-14. A query made by a user should include these attributes for UBI tracking.", + "type": "object", + "required": [ "user_query" ], + "properties": { + "query_id": { + "description": "The unique identifier of a query, typically a UUID, but can be any string.", + "oneOf": [ + { + "type": "string", + "format": "uuid", + "examples": ["00112233-4455-6677-8899-aabbccddeeff"] + }, + { + "type": "string", + "maxLength": 100, + "examples": ["1234-user-5678"] + } + ] + }, + "client_id": { + "description": "The client issuing the query. This could be a unique browser, a microservice that performs searches, a crawling bot.", + "type": "string", + "maxLength": 100, + "examples": ["5e3b2a1c-8b7d-4f2e-a3d4-c9b2e1f3a4b5","quepid-nightly-bot", "BugsBunny::Firefox@0967084"] + }, + "user_query":{ + "description": "The query as the user entered it. No length limit specified.", + "type": "string", + "$comment": "Currently not required to support recommendation systems etc that might not have a user generated query." + }, + "query_attributes":{ + "description": "Any query modifiers like filter choices or pagination. Other attributes such as experiment identifiers that need to be tracked with the query.", + "type": "object", + "additionalProperties": true + }, + "object_id_field":{ + "description": "The name of the field that has the id of the objects that will be stored in the backend queries data store. So it you have a query for products and want to save the SKUs, then this might be `sku` and if you are querying for people, maybe this is `ssn`. If you do not provide this value then the default primary identifier in your search index will be used. For example `_id` on OpenSearch. ", + "type": "string", + "maxLength": 100 + } + } +} diff --git a/schema/1.0.0/query.response.schema.json b/schema/1.0.0/query.response.schema.json new file mode 100644 index 0000000..af1e361 --- /dev/null +++ b/schema/1.0.0/query.response.schema.json @@ -0,0 +1,25 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://o19s.github.io/ubi/schema/1.0.0/query.response.schema.json", + "title": "Query Response When Using UBI", + "description": "Version 1.0.0; last updated 2024-06-14. The response to a query made by a user should support this schema.", + "type": "object", + "required": [ "query_id" ], + "properties": { + "query_id": { + "description": "The unique identifier of a query, typically a UUID, but can be any string.", + "oneOf": [ + { + "type": "string", + "format": "uuid", + "examples": ["00112233-4455-6677-8899-aabbccddeeff"] + }, + { + "type": "string", + "maxLength": 100, + "examples": ["1234-user-5678"] + } + ] + } + } +}