diff --git a/docs/html/1.3.0/event.schema.html b/docs/html/1.3.0/event.schema.html new file mode 100644 index 0000000..4a70113 --- /dev/null +++ b/docs/html/1.3.0/event.schema.html @@ -0,0 +1,1765 @@ + + + + + + + + + + + + + + + + Event tracking for UBI + +
+ + +
+ +

Event tracking for UBI

Type: object
+

Version 1.3.0; last updated 2025-01-22. 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"
+
+
+
+
+
+
+
+
+
+

+ +

+
+ +
+
+ +
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. Please note that Opensearch requires a trailing Z or explicit timezone offset.

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

+ +

+
+ +
+
+ +
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.3.0/query.request.schema.html b/docs/html/1.3.0/query.request.schema.html new file mode 100644 index 0000000..17e0dc0 --- /dev/null +++ b/docs/html/1.3.0/query.request.schema.html @@ -0,0 +1,566 @@ + + + + + + + + + + + + + + + + Query Tracking for UBI + +
+ + +
+ +

Query Tracking for UBI

Type: object
+

Version 1.3.0; last updated 2025-01-22. 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. Please note that Opensearch requires a trailing Z or explicit timezone offset.

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

+ +

+
+ +
+
+ +
root + + + + query_response_id
Type: string
+

The id of the search engine response.

+ + + + + + +
+
Examples:
+
"5e3b2a1c-8b7d-4f2e-a3d4-c9b2e1f3a4b5"
+
+
"00112233-4455-6677-8899-aabbccddeeff"
+
+
+
+
+
+
+
+
+
+

+ +

+
+ +
+
+ +
root + + + + query_response_hit_ids
Type: array of string
+

The ids of the documents that were returned by the search engine for this query in the order they were returned.

+ + + + + + + No Additional Items

Each item of this array must be:

+
+
+ + +
root + + + + query_response_hit_ids + + + + query_response_hit_ids items
Type: string
+ + + + + + + +
+

+
Examples:
+
[
+    "B07XLFYN6S",
+    "B013UFPODY",
+    "B07SHS91DQ",
+    "B077FVRM4P",
+    "B07ZCRSVBB",
+    "B07H7RWGRY",
+    "B085XP9ZY5",
+    "B01LW2UNZQ",
+    "B01MQVMFUN",
+    "B08KFPPJ3Y",
+    "B08THXDPVM",
+    "B07V2GZSMS",
+    "B0828XP9RM",
+    "B07G96L41J",
+    "B07V224V9X",
+    "B095LHL2G5",
+    "B083W38C8H",
+    "B06XWPHG53",
+    "B07J4WHNFC",
+    "B071HMM81V"
+]
+
+
[
+    "1",
+    "2",
+    "3",
+    "4",
+    "5"
+]
+
+
[]
+
+
+
+
+
+
+ + + \ No newline at end of file diff --git a/docs/html/1.3.0/query.response.schema.html b/docs/html/1.3.0/query.response.schema.html new file mode 100644 index 0000000..74a9822 --- /dev/null +++ b/docs/html/1.3.0/query.response.schema.html @@ -0,0 +1,157 @@ + + + + + + + + + + + + + + + + Query Response When Using UBI + +
+ + +
+ +

Query Response When Using UBI

Type: object
+

Version 1.3.0; last updated 2025-01-22. 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.3.0/schema_doc.css b/docs/html/1.3.0/schema_doc.css new file mode 100644 index 0000000..e1f3a51 --- /dev/null +++ b/docs/html/1.3.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.3.0/event.schema.json b/schema/1.3.0/event.schema.json new file mode 100644 index 0000000..51d1ca0 --- /dev/null +++ b/schema/1.3.0/event.schema.json @@ -0,0 +1,195 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://o19s.github.io/ubi/schema/1.3.0/event.schema.json", + "title": "Event tracking for UBI", + "description": "Version 1.3.0; last updated 2025-01-22. An event that occurred, typically in response to a user.", + "type": "object", + "required": ["action_name", "timestamp"], + "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" + ] + }, + "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. _Please note that Opensearch requires a trailing `Z` or explicit timezone offset._", + "type": "string", + "format": "date-time", + "examples": ["2018-11-13T20:20:39+00:00", "2018-11-13T20:20:39Z", "2018-11-13T20:20:39"] + }, + "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.3.0/query.request.schema.json b/schema/1.3.0/query.request.schema.json new file mode 100644 index 0000000..ef17f6f --- /dev/null +++ b/schema/1.3.0/query.request.schema.json @@ -0,0 +1,77 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://o19s.github.io/ubi/schema/1.3.0/query.request.schema.json", + "title": "Query Tracking for UBI", + "description": "Version 1.3.0; last updated 2025-01-22. A query made by a user should include these attributes for UBI tracking.", + "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": [ + { + "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. _Please note that Opensearch requires a trailing `Z` or explicit timezone offset._", + "type": "string", + "format": "date-time", + "examples": ["2018-11-13T20:20:39+00:00", "2018-11-13T20:20:39Z", "2018-11-13T20:20:39"] + }, + "query_response_id": { + "description": "The id of the search engine response.", + "type": "string", + "examples": ["5e3b2a1c-8b7d-4f2e-a3d4-c9b2e1f3a4b5", "00112233-4455-6677-8899-aabbccddeeff"] + }, + "query_response_hit_ids": { + "description": "The ids of the documents that were returned by the search engine for this query in the order they were returned.", + "type": "array", + "items": { + "type": "string" + }, + "examples": [["B07XLFYN6S", "B013UFPODY", "B07SHS91DQ", "B077FVRM4P", "B07ZCRSVBB", "B07H7RWGRY", "B085XP9ZY5", "B01LW2UNZQ", "B01MQVMFUN", "B08KFPPJ3Y", "B08THXDPVM", "B07V2GZSMS", "B0828XP9RM", "B07G96L41J", "B07V224V9X", "B095LHL2G5", "B083W38C8H", "B06XWPHG53", "B07J4WHNFC", "B071HMM81V"], ["1","2","3","4","5"], []] + } + } +} diff --git a/schema/1.3.0/query.response.schema.json b/schema/1.3.0/query.response.schema.json new file mode 100644 index 0000000..4cd8ad5 --- /dev/null +++ b/schema/1.3.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.3.0/query.response.schema.json", + "title": "Query Response When Using UBI", + "description": "Version 1.3.0; last updated 2025-01-22. 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"] + } + ] + } + } +}