diff --git a/README.md b/README.md index 5d3b8cd..a733e18 100644 --- a/README.md +++ b/README.md @@ -30,8 +30,9 @@ Many Search teams struggle with understanding "Why is my user doing this". They There are A LOT of tools out there for tracking events, Google Analytics, Snowplow, etc, but each is a bit different, and each tends to lock you in. None of them think about the needs of Search teams specifically either. The User Behavior Insights standard attempts to provide a search focused standard that can operate across many platforms. There are implementations for - * [OpenSearch](https://github.com/o19s/documentation-website/tree/ubi-docs-consolidation/_search-plugins/ubi) + * [OpenSearch](https://opensearch.org/docs/latest/search-plugins/ubi) * [Apache Solr](https://github.com/apache/solr/pull/2452) + * [Elasticsearch](https://github.com/o19s/user-behavior-insights-elasticsearch) ## 🪛 How to use it @@ -41,9 +42,9 @@ UBI requires coordination between the client (a browser, a mobile app, etc) and | JSON Schema | HTML Docs | | --- | --- | - [query.request.schema.json](https://o19s.github.io/ubi/schema/1.1.0/query.request.schema.json) | [query.request.schema.html](https://o19s.github.io/ubi/docs/html/1.1.0/query.request.schema.html) | -| [query.response.schema.json](https://o19s.github.io/ubi/schema/1.1.0/query.response.schema.json) | [query.response.schema.html](https://o19s.github.io/ubi/docs/html/1.1.0/query.response.schema.html) | -| [event.schema.json](https://o19s.github.io/ubi/schema/1.1.0/event.schema.json) | [event.schema.html](https://o19s.github.io/ubi/docs/html/1.1.0/event.schema.html) | + [query.request.schema.json](https://o19s.github.io/ubi/schema/1.2.0/query.request.schema.json) | [query.request.schema.html](https://o19s.github.io/ubi/docs/html/1.2.0/query.request.schema.html) | +| [query.response.schema.json](https://o19s.github.io/ubi/schema/1.2.0/query.response.schema.json) | [query.response.schema.html](https://o19s.github.io/ubi/docs/html/1.2.0/query.response.schema.html) | +| [event.schema.json](https://o19s.github.io/ubi/schema/1.2.0/event.schema.json) | [event.schema.html](https://o19s.github.io/ubi/docs/html/1.2.0/event.schema.html) | You just need to copy, download or reference one of the schema files to validate a UBI data structure, built as a JSON file from scratch, or a JSON generated previously (for example, [these samples](https://github.com/o19s/ubi/blob/master/samples/)). diff --git a/docs/html/event.schema.html b/docs/html/1.0.0/event.schema.html similarity index 100% rename from docs/html/event.schema.html rename to docs/html/1.0.0/event.schema.html diff --git a/docs/html/query.request.schema.html b/docs/html/1.0.0/query.request.schema.html similarity index 100% rename from docs/html/query.request.schema.html rename to docs/html/1.0.0/query.request.schema.html diff --git a/docs/html/query.response.schema.html b/docs/html/1.0.0/query.response.schema.html similarity index 100% rename from docs/html/query.response.schema.html rename to docs/html/1.0.0/query.response.schema.html diff --git a/docs/html/schema_doc.css b/docs/html/1.0.0/schema_doc.css similarity index 100% rename from docs/html/schema_doc.css rename to docs/html/1.0.0/schema_doc.css diff --git a/docs/html/schema_doc.min.js b/docs/html/1.0.0/schema_doc.min.js similarity index 100% rename from docs/html/schema_doc.min.js rename to docs/html/1.0.0/schema_doc.min.js diff --git a/out/event.schema.json b/out/event.schema.json deleted file mode 100644 index c24bcbc..0000000 --- a/out/event.schema.json +++ /dev/null @@ -1 +0,0 @@ -{"$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. If only authenticated users are tracked, then you could use a specific user id here, otherwise you should use something permanent and track user id as an _Additional Property_.","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. A common example of an _Additional Properties_ is the specific identifier of the user (`user_id`). Note: a user identifier is different then the required `client_id` attribute.","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/out/query.request.schema.json b/out/query.request.schema.json deleted file mode 100644 index ad8f8c7..0000000 --- a/out/query.request.schema.json +++ /dev/null @@ -1 +0,0 @@ -{"$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. If only authenticated users are tracked, then you could use a specific user id here, otherwise you should use something permanent and track user id as an _Additional Property_.","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/out/query.response.schema.json b/out/query.response.schema.json deleted file mode 100644 index 8034dd8..0000000 --- a/out/query.response.schema.json +++ /dev/null @@ -1 +0,0 @@ -{"$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"]}]}}} diff --git a/schema/1.2.0/event.schema.json b/schema/1.2.0/event.schema.json index 8cc2aa5..24439fe 100644 --- a/schema/1.2.0/event.schema.json +++ b/schema/1.2.0/event.schema.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://o19s.github.io/ubi/schema/1.2.0/event.schema.json", "title": "Event tracking for UBI", - "description": "Version 1.2.0; last updated 2024-???. An event that occurred, typically in response to a user.", + "description": "Version 1.2.0; last updated 2024-10-24. An event that occurred, typically in response to a user.", "type": "object", "required": ["action_name", "timestamp"], "properties": { diff --git a/schema/1.2.0/query.request.schema.json b/schema/1.2.0/query.request.schema.json index ca7b402..f26abe9 100644 --- a/schema/1.2.0/query.request.schema.json +++ b/schema/1.2.0/query.request.schema.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://o19s.github.io/ubi/schema/1.2.0/query.request.schema.json", "title": "Query Tracking for UBI", - "description": "Version 1.2.0; last updated 2024-??. A query made by a user should include these attributes for UBI tracking.", + "description": "Version 1.2.0; last updated 2024-10-24. A query made by a user should include these attributes for UBI tracking.", "type": "object", "required": [ "user_query" ], "properties": { diff --git a/schema/1.2.0/query.response.schema.json b/schema/1.2.0/query.response.schema.json index 7831811..c5ac3c9 100644 --- a/schema/1.2.0/query.response.schema.json +++ b/schema/1.2.0/query.response.schema.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://o19s.github.io/ubi/schema/1.2.0/query.response.schema.json", "title": "Query Response When Using UBI", - "description": "Version 1.2.0; last updated 2024-??. The response to a query made by a user should support this schema.", + "description": "Version 1.2.0; last updated 2024-10-24. The response to a query made by a user should support this schema.", "type": "object", "required": [ "query_id" ], "properties": {