From e8cd9e9a2bf616531661f3efbdbc023403c4852e Mon Sep 17 00:00:00 2001 From: Eric Pugh Date: Wed, 23 Oct 2024 09:10:47 -0400 Subject: [PATCH 1/3] Fixes #27 by clarifying the format is ISO standard --- schema/1.1.0/event.schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schema/1.1.0/event.schema.json b/schema/1.1.0/event.schema.json index 6d3c12e..178d9ee 100644 --- a/schema/1.1.0/event.schema.json +++ b/schema/1.1.0/event.schema.json @@ -64,7 +64,7 @@ "examples": ["5e3b2a1c-8b7d-4f2e-a3d4-c9b2e1f3a4b5"] }, "timestamp": { - "description": "When the event took place.", + "description": "When the event took place. This timestamp is formatted according to the ISO 8601 standard.", "type": "string", "format": "date-time", "examples": ["2018-11-13T20:20:39+00:00"] From 50575557655978508bfc003f0e1bfc7cf4358050 Mon Sep 17 00:00:00 2001 From: Eric Pugh Date: Wed, 23 Oct 2024 10:14:42 -0400 Subject: [PATCH 2/3] Updated version based on discussion, and bump to 1.2.0 --- DEVELOPMENT.md | 23 +-- docs/html/1.2.0/event.schema.html | 22 +++ docs/html/1.2.0/query.request.schema.html | 7 + docs/html/1.2.0/query.response.schema.html | 3 + docs/html/1.2.0/schema_doc.css | 181 +++++++++++++++++++ schema/1.2.0/event.schema.json | 193 +++++++++++++++++++++ schema/1.2.0/query.request.schema.json | 52 ++++++ schema/1.2.0/query.response.schema.json | 25 +++ 8 files changed, 495 insertions(+), 11 deletions(-) create mode 100644 docs/html/1.2.0/event.schema.html create mode 100644 docs/html/1.2.0/query.request.schema.html create mode 100644 docs/html/1.2.0/query.response.schema.html create mode 100644 docs/html/1.2.0/schema_doc.css create mode 100644 schema/1.2.0/event.schema.json create mode 100644 schema/1.2.0/query.request.schema.json create mode 100644 schema/1.2.0/query.response.schema.json diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 0052ab1..ffc26e3 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,24 +1,25 @@ -To generate the docs: +#### To generate the docs: -``` -npm install -g @adobe/jsonschema2md - -jsonschema2md -d schema -o docs/schema -# generated output for whole folder is written to ./docs/schema -``` - -OR ``` pip install json-schema-for-humans -/Users/epugh/.asdf/installs/python/3.9.17/bin/generate-schema-doc --config-file jsfh-conf.yaml /Users/epugh/Documents/projects/ubi/schema/1.1.0/ /Users/epugh/Documents/projects/ubi/docs/html/1.1.0 +export UBI_VERSION=1.2.0 + +mkdir docs/html/${UBI_VERSION} +/Users/epugh/.asdf/installs/python/3.9.17/bin/generate-schema-doc --config-file jsfh-conf.yaml ./schema/$UBI_VERSION/ ./docs/html/$UBI_VERSION # generated html for whole folder is written to ./docs/html ``` We then check them into Github. +https://o19s.github.io/blob/main/docs/ -https://o19s.github.io/blob/main/docs/ +#### To release UBI + +1. Make sure to copy the last version (i.e. `schema/1.2.0)` to the next version (i.e. `schema/1.3.0`) +1. Make sure to update the version information in each .json file. +1. Build the docs into ./docs/html/1.3.0 +1. Update the home README.md file to point to the new version. diff --git a/docs/html/1.2.0/event.schema.html b/docs/html/1.2.0/event.schema.html new file mode 100644 index 0000000..70e10a8 --- /dev/null +++ b/docs/html/1.2.0/event.schema.html @@ -0,0 +1,22 @@ + Event tracking for UBI

Event tracking for UBI

Type: object

Version 1.2.0; last updated 2024-???. An event that occurred, typically in response to a user.

root application
Type: string

name of the application tracking UBI events.

Must be at most 100 characters long


Examples:

"amazon-shop"
+
"ABC-microservice"
+
"doctor-search"
+

root action_name

The name of the action that triggered the event. We have a set of common defaults, however you can pass in whatever you want.

root action_name oneOf item 0
Type: enum (of string)

Must be one of:

  • "click_through"
  • "add_to_cart"
  • "click"
  • "watch"
  • "view"
  • "purchase"
  • "impression"
root action_name oneOf item 1
Type: string

Must be at most 100 characters long

root query_id

The unique identifier of a query, typically a UUID, but can be any string.

root query_id oneOf item 0
Type: stringFormat: uuid

Example:

"00112233-4455-6677-8899-aabbccddeeff"
+
root query_id oneOf item 1
Type: string

Must be at most 100 characters long


Example:

"1234-user-5678"
+

root session_id
Type: string

The session of the user creating the interactions. This allows us to correlate the interactions with the other events created by a service that recognizes session IDs. Can be used to track unique visits for authenticated and anonymous users.

Must be at most 100 characters long


Example:

"84266fdbd31d4c2c6d0665f7e8380fa3"
+

root client_id
Type: string

The client issuing the query. This could be a unique browser, a microservice that performs searches, a crawling bot.

Must be at most 100 characters long


Examples:

"5e3b2a1c-8b7d-4f2e-a3d4-c9b2e1f3a4b5"
+
"quepid-nightly-bot"
+
"BugsBunny::Firefox@0967084"
+

root user_id
Type: string

The user ID associated with the person performing the interactions being logged on the site. Can be null/empty in case of an unauthenticated user.

Must be at most 100 characters long


Example:

"5e3b2a1c-8b7d-4f2e-a3d4-c9b2e1f3a4b5"
+

root timestamp
Type: stringFormat: date-time

When the event took place. This timestamp is formatted according to the ISO 8601 standard.
Example:

"2018-11-13T20:20:39+00:00"
+

root message_type
Type: string

Group various action_name's into logical bins.

Must be at most 100 characters long


Examples:

"QUERY"
+
"CONVERSION"
+

root message
Type: string

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.

Must be at most 1024 characters long

root event_attributes
Type: object

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.

root event_attributes object
Type: object

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..).

root event_attributes object object_id

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.

root event_attributes object object_id anyOf item 0
Type: string

Must be at most 256 characters long

root event_attributes object object_id anyOf item 1
Type: integer

Examples:

"XYZ-12345"
+
"ISBN 0-061-96436-0"
+
"123"
+

root event_attributes object object_id_type

The type of the object id that the user is searching for. For a social e-commerce site, these could include product, user, post, comment and so on.

root event_attributes object object_id_type oneOf item 0
Type: enum (of string)

Must be one of:

  • "product"
  • "user"
  • "post"
  • "comment"
  • "video"
root event_attributes object object_id_type oneOf item 1
Type: string

Must be at most 100 characters long

root event_attributes object object_id_field
Type: string

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.

Must be at most 100 characters long

root event_attributes object internal_id

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.

root event_attributes object internal_id anyOf item 0
Type: string

Must be at most 256 characters long

root event_attributes object internal_id anyOf item 1
Type: integer

Examples:

"1"
+
"123456"
+

Additional Properties of any type are allowed.

root event_attributes object additionalProperties
Type: object

root event_attributes position

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.

root event_attributes position oneOf item 0
Type: object

root event_attributes position oneOf item 0 ordinal
Type: object

The nth position of the document on the search results page.

root event_attributes position oneOf item 0 ordinal index
Type: integer

The position of the document. For grid layout this would be left to right, ignoring wrapping.
Examples:

1
+
3
+
24
+
root event_attributes position oneOf item 1
Type: object

root event_attributes position oneOf item 1 xy
Type: object

The x,y coordinates on the screen for triggering an event.

root event_attributes position oneOf item 1 xy x
Type: number

The horizontal location on the page or screen of the event.

root event_attributes position oneOf item 1 xy y
Type: number

The vertical location on the page or screen of the event.

Additional Properties of any type are allowed.

root event_attributes position additionalProperties
Type: object

Additional Properties of any type are allowed.

root event_attributes additionalProperties
Type: object
\ No newline at end of file diff --git a/docs/html/1.2.0/query.request.schema.html b/docs/html/1.2.0/query.request.schema.html new file mode 100644 index 0000000..3514458 --- /dev/null +++ b/docs/html/1.2.0/query.request.schema.html @@ -0,0 +1,7 @@ + Query Tracking for UBI

Query Tracking for UBI

Type: object

Version 1.2.0; last updated 2024-??. A query made by a user should include these attributes for UBI tracking.

root query_id

The unique identifier of a query, typically a UUID, but can be any string.

root query_id oneOf item 0
Type: stringFormat: uuid

Example:

"00112233-4455-6677-8899-aabbccddeeff"
+
root query_id oneOf item 1
Type: string

Must be at most 100 characters long


Example:

"1234-user-5678"
+

root client_id
Type: string

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.

Must be at most 100 characters long


Examples:

"5e3b2a1c-8b7d-4f2e-a3d4-c9b2e1f3a4b5"
+
"quepid-nightly-bot"
+
"BugsBunny::Firefox@0967084"
+

root user_query
Type: string

The query as the user entered it. No length limit specified.

root query_attributes
Type: object

Any query modifiers like filter choices or pagination. Other attributes such as experiment identifiers that need to be tracked with the query.

Additional Properties of any type are allowed.

root query_attributes additionalProperties
Type: object

root object_id_field
Type: string

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.

Must be at most 100 characters long

root timestamp
Type: stringFormat: date-time

When the query was issued. This timestamp is formatted according to the ISO 8601 standard. In many implementations of the UBI Query plugin the timestamp will be set for you at the time of the query being run. If you are replaying data, or want to track the timezone of the caller specifically, instead of using the search engine's timezone, then you will need to provide the timestamp instead.
Example:

"2018-11-13T20:20:39+00:00"
+
\ No newline at end of file diff --git a/docs/html/1.2.0/query.response.schema.html b/docs/html/1.2.0/query.response.schema.html new file mode 100644 index 0000000..cae68ed --- /dev/null +++ b/docs/html/1.2.0/query.response.schema.html @@ -0,0 +1,3 @@ + Query Response When Using UBI

Query Response When Using UBI

Type: object

Version 1.2.0; last updated 2024-??. The response to a query made by a user should support this schema.

root query_id

The unique identifier of a query, typically a UUID, but can be any string.

root query_id oneOf item 0
Type: stringFormat: uuid

Example:

"00112233-4455-6677-8899-aabbccddeeff"
+
root query_id oneOf item 1
Type: string

Must be at most 100 characters long


Example:

"1234-user-5678"
+
\ No newline at end of file diff --git a/docs/html/1.2.0/schema_doc.css b/docs/html/1.2.0/schema_doc.css new file mode 100644 index 0000000..e1f3a51 --- /dev/null +++ b/docs/html/1.2.0/schema_doc.css @@ -0,0 +1,181 @@ +body { + font: 16px/1.5em "Overpass", "Open Sans", Helvetica, sans-serif; + color: #333; + font-weight: 300; + padding: 40px; +} + +.btn.btn-link { + font-size: 18px; + user-select: text; +} + +.jsfh-animated-property { + animation: eclair; + animation-iteration-count: 1; + animation-fill-mode: forwards; + animation-duration: .75s; + +} + +@keyframes eclair { + 0%,100% { + transform: scale(1); + } + 50% { + transform: scale(1.03); + } +} + +.btn.btn-primary { + margin: 10px; +} + +.btn.example-show.collapsed:before { + content: "show" +} + +.btn.example-show:before { + content: "hide" +} + +.description.collapse:not(.show) { + max-height: 100px !important; + overflow: hidden; + + display: -webkit-box; + -webkit-line-clamp: 2; + -webkit-box-orient: vertical; +} + +.description.collapsing { + min-height: 100px !important; +} + +.collapse-description-link.collapsed:after { + content: '+ Read More'; +} + +.collapse-description-link:not(.collapsed):after { + content: '- Read Less'; +} + +.badge { + font-size: 100%; + margin-bottom: 0.5rem; + margin-top: 0.5rem; +} + +.badge.value-type { + font-size: 120%; + margin-right: 5px; + margin-bottom: 10px; +} + + +.badge.default-value { + font-size: 120%; + margin-left: 5px; + margin-bottom: 10px; +} + +.badge.restriction { + display: inline-block; +} + +.badge.required-property,.badge.deprecated-property,.badge.pattern-property,.badge.no-additional { + font-size: 100%; + margin-left: 10px; +} + +.accordion div.card:only-child { + border-bottom: 1px solid rgba(0, 0, 0, 0.125); +} + +.examples { + padding: 1rem !important; +} + +.examples pre { + margin-bottom: 0; +} + +.highlight.jumbotron { + padding: 1rem !important; +} + +.generated-by-footer { + margin-top: 1em; + text-align: right; +} + +/* From https://github.com/richleland/pygments-css/blob/master/friendly.css, see https://github.com/trentm/python-markdown2/wiki/fenced-code-blocks */ +.highlight { background: #e9ecef; } /* Changed from #f0f0f0 in the original style to be the same as bootstrap's jumbotron */ +.highlight .hll { background-color: #ffffcc } +.highlight .c { color: #60a0b0; font-style: italic } /* Comment */ +.highlight .err { border: 1px solid #FF0000 } /* Error */ +.highlight .k { color: #007020; font-weight: bold } /* Keyword */ +.highlight .o { color: #666666 } /* Operator */ +.highlight .ch { color: #60a0b0; font-style: italic } /* Comment.Hashbang */ +.highlight .cm { color: #60a0b0; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #007020 } /* Comment.Preproc */ +.highlight .cpf { color: #60a0b0; font-style: italic } /* Comment.PreprocFile */ +.highlight .c1 { color: #60a0b0; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #60a0b0; background-color: #fff0f0 } /* Comment.Special */ +.highlight .gd { color: #A00000 } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .gr { color: #FF0000 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #00A000 } /* Generic.Inserted */ +.highlight .go { color: #888888 } /* Generic.Output */ +.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #0044DD } /* Generic.Traceback */ +.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #007020 } /* Keyword.Pseudo */ +.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #902000 } /* Keyword.Type */ +.highlight .m { color: #40a070 } /* Literal.Number */ +.highlight .s { color: #4070a0 } /* Literal.String */ +.highlight .na { color: #4070a0 } /* Name.Attribute */ +.highlight .nb { color: #007020 } /* Name.Builtin */ +.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */ +.highlight .no { color: #60add5 } /* Name.Constant */ +.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */ +.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */ +.highlight .ne { color: #007020 } /* Name.Exception */ +.highlight .nf { color: #06287e } /* Name.Function */ +.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */ +.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ +.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #bb60d5 } /* Name.Variable */ +.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */ +.highlight .w { color: #bbbbbb } /* Text.Whitespace */ +.highlight .mb { color: #40a070 } /* Literal.Number.Bin */ +.highlight .mf { color: #40a070 } /* Literal.Number.Float */ +.highlight .mh { color: #40a070 } /* Literal.Number.Hex */ +.highlight .mi { color: #40a070 } /* Literal.Number.Integer */ +.highlight .mo { color: #40a070 } /* Literal.Number.Oct */ +.highlight .sa { color: #4070a0 } /* Literal.String.Affix */ +.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */ +.highlight .sc { color: #4070a0 } /* Literal.String.Char */ +.highlight .dl { color: #4070a0 } /* Literal.String.Delimiter */ +.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #4070a0 } /* Literal.String.Double */ +.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ +.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */ +.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ +.highlight .sx { color: #c65d09 } /* Literal.String.Other */ +.highlight .sr { color: #235388 } /* Literal.String.Regex */ +.highlight .s1 { color: #4070a0 } /* Literal.String.Single */ +.highlight .ss { color: #517918 } /* Literal.String.Symbol */ +.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #06287e } /* Name.Function.Magic */ +.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */ +.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */ +.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */ +.highlight .vm { color: #bb60d5 } /* Name.Variable.Magic */ +.highlight .il { color: #40a070 } /* Literal.Number.Integer.Long */ diff --git a/schema/1.2.0/event.schema.json b/schema/1.2.0/event.schema.json new file mode 100644 index 0000000..126d7c6 --- /dev/null +++ b/schema/1.2.0/event.schema.json @@ -0,0 +1,193 @@ +{ + "$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.", + "type": "object", + "required": ["action_name", "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", "impression"] + }, + { + "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"] + } + ] + }, + "session_id": { + "description": "The session of the user creating the interactions. This allows us to correlate the interactions with the other events created by a service that recognizes session IDs. Can be used to track unique visits for authenticated and anonymous users.", + "type": "string", + "maxLength": 100, + "examples": ["84266fdbd31d4c2c6d0665f7e8380fa3"] + }, + "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_id": { + "description": "The user ID associated with the person performing the interactions being logged on the site. Can be null/empty in case of an unauthenticated user.", + "type": "string", + "maxLength": 100, + "examples": ["5e3b2a1c-8b7d-4f2e-a3d4-c9b2e1f3a4b5"] + }, + "timestamp": { + "description": "When the event took place. This timestamp is formatted according to the ISO 8601 standard.", + "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_type": { + "description": "The type of the object id that the user is searching for. For a social e-commerce site, these could include product, user, post, comment and so on.", + "oneOf": [ + { + "type": "string", + "maxLength": 100, + "enum": ["product", "user", "post", "comment", "video"] + }, + { + "type": "string", + "maxLength": 100 + } + ] + }, + "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.2.0/query.request.schema.json b/schema/1.2.0/query.request.schema.json new file mode 100644 index 0000000..2cdad1a --- /dev/null +++ b/schema/1.2.0/query.request.schema.json @@ -0,0 +1,52 @@ +{ + "$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.", + "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 + }, + "timestamp": { + "description": "When the query was issued. This timestamp is formatted according to the ISO 8601 standard. In many implementations of the UBI Query plugin the timestamp will be set for you at the time of the query being run. If you are replaying data, or want to track the timezone of the caller specifically, instead of using the search engine's timezone, then you will need to provide the timestamp instead.", + "type": "string", + "format": "date-time", + "examples": ["2018-11-13T20:20:39+00:00"] + } + } +} diff --git a/schema/1.2.0/query.response.schema.json b/schema/1.2.0/query.response.schema.json new file mode 100644 index 0000000..7831811 --- /dev/null +++ b/schema/1.2.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.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.", + "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"] + } + ] + } + } +} From 0da5e0c92e9325d4ed4b54c1468fd4a52b7e79d3 Mon Sep 17 00:00:00 2001 From: Eric Pugh Date: Wed, 23 Oct 2024 13:28:28 -0400 Subject: [PATCH 3/3] Add in application examples --- docs/html/1.2.0/event.schema.html | 10 ++++++---- docs/html/1.2.0/query.request.schema.html | 9 +++++++-- docs/html/1.2.0/query.response.schema.html | 2 +- schema/1.2.0/event.schema.json | 4 +++- schema/1.2.0/query.request.schema.json | 12 ++++++++++++ 5 files changed, 29 insertions(+), 8 deletions(-) diff --git a/docs/html/1.2.0/event.schema.html b/docs/html/1.2.0/event.schema.html index 70e10a8..48bd10b 100644 --- a/docs/html/1.2.0/event.schema.html +++ b/docs/html/1.2.0/event.schema.html @@ -1,6 +1,8 @@ - Event tracking for UBI

Event tracking for UBI

Type: object

Version 1.2.0; last updated 2024-???. An event that occurred, typically in response to a user.

root application
Type: string

name of the application tracking UBI events.

Must be at most 100 characters long


Examples:

"amazon-shop"
-
"ABC-microservice"
-
"doctor-search"
+ Event tracking for UBI 
   
 
 
Event tracking for UBI
Type: object
 
Version 1.2.0; last updated 2024-???. An event that occurred, typically in response to a user.
  
 
 
 
  
 
 
 
 
root    application
Type: string
 
Name of the application that is integrated with UBI. You can think of application as in a source of search queries. For example, if you have a type ahead and a traditional search UI, then you might have type-ahead and primary-search as values.
  
Must be at most 100 characters long
 
 
Examples:
 
"type-ahead"
+
 
"primary-search"
+
 
"amazon-shop"
+
 
"ABC-microservice"
+
 
"doctor-search"
 
 
 
 
 
 
 
 
 
 
  
 
 
 
 
root    action_name

 
The name of the action that triggered the event. We have a set of common defaults, however you can pass in whatever you want.
 
  
 
 
root    action_name    oneOf    item 0
Type: enum (of string)
 
 
Must be one of:
 
  • "click_through"
  • "add_to_cart"
  • "click"
  • "watch"
  • "view"
  • "purchase"
  • "impression"
 
 
 
root    action_name    oneOf    item 1
Type: string
 
Must be at most 100 characters long
 
 
 
 
 
 
 
 
 
  
 
 
 
 
root    query_id

 
The unique identifier of a query, typically a UUID, but can be any string.
 
  
 
 
root    query_id    oneOf    item 0
Type: stringFormat: uuid
 
 
Example:
 
"00112233-4455-6677-8899-aabbccddeeff"
 
 
 
 
root    query_id    oneOf    item 1
Type: string
 
Must be at most 100 characters long
 
 
Example:
 
"1234-user-5678"
 
 
 
 
 
 
 
 
 
 
 
  
 
 
 
 
root    session_id
Type: string
 
The session of the user creating the interactions. This allows us to correlate the interactions with the other events created by a service that recognizes session IDs. Can be used to track unique visits for authenticated and anonymous users.
  
Must be at most 100 characters long
 
 
Example:
 
"84266fdbd31d4c2c6d0665f7e8380fa3"
@@ -19,4 +21,4 @@
 
 
 
 
 
 
 
 
 
 
  
 
 
 
Additional Properties of any type are allowed.
 
root    event_attributes    object    additionalProperties
Type: object

root event_attributes position

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.

root event_attributes position oneOf item 0
Type: object

root event_attributes position oneOf item 0 ordinal
Type: object

The nth position of the document on the search results page.

root event_attributes position oneOf item 0 ordinal index
Type: integer

The position of the document. For grid layout this would be left to right, ignoring wrapping.
Examples:

1
 
3
 
24
-
root event_attributes position oneOf item 1
Type: object

root event_attributes position oneOf item 1 xy
Type: object

The x,y coordinates on the screen for triggering an event.

root event_attributes position oneOf item 1 xy x
Type: number

The horizontal location on the page or screen of the event.

root event_attributes position oneOf item 1 xy y
Type: number

The vertical location on the page or screen of the event.

Additional Properties of any type are allowed.

root event_attributes position additionalProperties
Type: object

Additional Properties of any type are allowed.

root event_attributes additionalProperties
Type: object
\ No newline at end of file +
root event_attributes position oneOf item 1
Type: object

root event_attributes position oneOf item 1 xy
Type: object

The x,y coordinates on the screen for triggering an event.

root event_attributes position oneOf item 1 xy x
Type: number

The horizontal location on the page or screen of the event.

root event_attributes position oneOf item 1 xy y
Type: number

The vertical location on the page or screen of the event.

Additional Properties of any type are allowed.

root event_attributes position additionalProperties
Type: object

Additional Properties of any type are allowed.

root event_attributes additionalProperties
Type: object
\ No newline at end of file diff --git a/docs/html/1.2.0/query.request.schema.html b/docs/html/1.2.0/query.request.schema.html index 3514458..6084c4d 100644 --- a/docs/html/1.2.0/query.request.schema.html +++ b/docs/html/1.2.0/query.request.schema.html @@ -1,7 +1,12 @@ - Query Tracking for UBI

Query Tracking for UBI

Type: object

Version 1.2.0; last updated 2024-??. A query made by a user should include these attributes for UBI tracking.

root query_id

The unique identifier of a query, typically a UUID, but can be any string.

root query_id oneOf item 0
Type: stringFormat: uuid

Example:

"00112233-4455-6677-8899-aabbccddeeff"
+ Query Tracking for UBI 
   
 
 
Query Tracking for UBI
Type: object
 
Version 1.2.0; last updated 2024-??. A query made by a user should include these attributes for UBI tracking.
  
 
 
 
  
 
 
 
 
root    application
Type: string
 
Name of the application that is integrated with UBI. You can think of application as in a source of search queries. For example, if you have a type ahead and a traditional search UI, then you might have type-ahead and primary-search as values.
  
Must be at most 100 characters long
 
 
Examples:
 
"type-ahead"
+
 
"primary-search"
+
 
"amazon-shop"
+
 
"ABC-microservice"
+
 
"doctor-search"
+
 
 
 
 
 
 
 
 
 
  
 
 
 
 
root    query_id

 
The unique identifier of a query, typically a UUID, but can be any string.
 
  
 
 
root    query_id    oneOf    item 0
Type: stringFormat: uuid
 
 
Example:
 
"00112233-4455-6677-8899-aabbccddeeff"
 
 
 
 
root    query_id    oneOf    item 1
Type: string
 
Must be at most 100 characters long
 
 
Example:
 
"1234-user-5678"
 
 
 
 
 
 
 
 
 
 
 
  
 
 
 
 
root    client_id
Type: string
 
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.
  
Must be at most 100 characters long
 
 
Examples:
 
"5e3b2a1c-8b7d-4f2e-a3d4-c9b2e1f3a4b5"
 
 
"quepid-nightly-bot"
 
 
"BugsBunny::Firefox@0967084"
 
 
 
 
 
 
 
 
 
 
  
 
 
 
 
root    user_query
Type: string
 
The query as the user entered it. No length limit specified.
  
 
 
 
 
 
 
 
  
 
 
 
 
root    query_attributes
Type: object
 
Any query modifiers like filter choices or pagination. Other attributes such as experiment identifiers that need to be tracked with the query.
  
 
 
 
  
 
 
 
Additional Properties of any type are allowed.
 
root    query_attributes    additionalProperties
Type: object
 
 
 
 
 
 
 
 
 
 
 
 
  
 
 
 
 
root    object_id_field
Type: string
 
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. 
  
Must be at most 100 characters long
 
 
 
 
 
 
 
 
  
 
 
 
 
root    timestamp
Type: stringFormat: date-time
 
When the query was issued. This timestamp is formatted according to the ISO 8601 standard. In many implementations of the UBI Query plugin the timestamp will be set for you at the time of the query being run. If you are replaying data, or want to track the timezone of the caller specifically, instead of using the search engine's timezone, then you will need to provide the timestamp instead.
  
 
Example:
 
"2018-11-13T20:20:39+00:00"
-
 
 
 
 
 
  
\ No newline at end of file
+
\ No newline at end of file diff --git a/docs/html/1.2.0/query.response.schema.html b/docs/html/1.2.0/query.response.schema.html index cae68ed..11ce200 100644 --- a/docs/html/1.2.0/query.response.schema.html +++ b/docs/html/1.2.0/query.response.schema.html @@ -1,3 +1,3 @@ Query Response When Using UBI

Query Response When Using UBI

Type: object

Version 1.2.0; last updated 2024-??. The response to a query made by a user should support this schema.

root query_id

The unique identifier of a query, typically a UUID, but can be any string.

root query_id oneOf item 0
Type: stringFormat: uuid

Example:

"00112233-4455-6677-8899-aabbccddeeff"
root query_id oneOf item 1
Type: string

Must be at most 100 characters long


Example:

"1234-user-5678"
-
\ No newline at end of file +
\ No newline at end of file diff --git a/schema/1.2.0/event.schema.json b/schema/1.2.0/event.schema.json index 126d7c6..8cc2aa5 100644 --- a/schema/1.2.0/event.schema.json +++ b/schema/1.2.0/event.schema.json @@ -7,10 +7,12 @@ "required": ["action_name", "timestamp"], "properties": { "application": { - "description": "name of the application tracking UBI events.", + "description": "Name of the application that is integrated with UBI. You can think of application as in a source of search queries. For example, if you have a type ahead and a traditional search UI, then you might have `type-ahead` and `primary-search` as values.", "type": "string", "maxLength": 100, "examples": [ + "type-ahead", + "primary-search", "amazon-shop", "ABC-microservice", "doctor-search" diff --git a/schema/1.2.0/query.request.schema.json b/schema/1.2.0/query.request.schema.json index 2cdad1a..ca7b402 100644 --- a/schema/1.2.0/query.request.schema.json +++ b/schema/1.2.0/query.request.schema.json @@ -6,6 +6,18 @@ "type": "object", "required": [ "user_query" ], "properties": { + "application": { + "description": "Name of the application that is integrated with UBI. You can think of application as in a source of search queries. For example, if you have a type ahead and a traditional search UI, then you might have `type-ahead` and `primary-search` as values.", + "type": "string", + "maxLength": 100, + "examples": [ + "type-ahead", + "primary-search", + "amazon-shop", + "ABC-microservice", + "doctor-search" + ] + }, "query_id": { "description": "The unique identifier of a query, typically a UUID, but can be any string.", "oneOf": [