-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
restore 1.0.0 version of spec from tagged release
- Loading branch information
Showing
3 changed files
with
238 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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"] | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| } | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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"] | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| } |