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"] + } + ] + } + } +}