# Data Structures

# Aggregation

An object that represents an aggregation over a result set.

# Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the aggregation. This will often be the field or field alias against which this aggregation is performed."
    },
    "entries": {
      "type": "array",
      "description": "The entries/buckets for this aggregation",
      "items": {
        "type": "object",
        "description": "An individual entry/bucket",
        "properties": {
          "value": {
            "type": "string",
            "description": "The value/key associated with this bucket. This may be a specific value for a given field or a date range, for instance."
          },
          "count": {
            "type": "integer",
            "description": "The number of results associated with this value."
          }
        }
      }
    },
    "total": {
      "type": "integer",
      "description": "The total number of results associated with this aggregation. If this is a terms aggregation, for instance, then this will be the total number of results for which this field exists."
    },
    "other": {
      "type": "integer",
      "description": "The number of results associated with this aggregation that are not accounted for in the 'entries' list."
    }
  }
}

# Example

{
  "name": "status",
  "entries": [
    {
      "value": "ok",
      "count": 516
    },
    {
      "value": "error",
      "count": 11
    }
  ],
  "total": 670,
  "other": 143
}

# BaseView

# Properties

Property	Type	Default	Description
name	String	n/a (required)	The name of the view
type	String	data	The type of view.
paths	String[]	n/a (required)	The URI path(s) to which this view is bound. Paths must be expressed using Spring PathPattern syntax, which supports template variables and wildcards.
methods	Enum[]: HttpRequestMethod	[ GET ]	The HTTP method(s) to which this view is bound.

# CustomPagedRequest

# Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "from": {
      "type": "integer",
      "description": "The zero-based result offset"
    },
    "size": {
      "type": "integer",
      "description": "The maximum number of results to retrieve"
    },
    "additionalProperties": {
      "description": "Any additional fields are allowed"
    }
  }
}

# Example

{
  "from": 20,
  "size": 15,
  "additional_field": "Hello, world!"
}

# DataServiceRequest

# Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "profile": {
      "type": "string"
    },
    "request": {}
  }
}

# Example

{
  "profile": "my-profile",
  "request": {
    "search_string": "John Smith",
    "date_min": "2011",
    "date_max": "2020",
    "offset": 0,
    "limit": 10
  }
}

# DataServiceResponse

# Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        },
        "cause": {
          "type": "string"
        }
      }
    }
  },
  "type": "object",
  "properties": {
    "datasets": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "data": {},
                "source": {}
              }
            }
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/error"
            }
          },
          "stats": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "latency": {
                "type": "integer"
              }
            }
          },
          "found": {
            "type": "boolean"
          }
        }
      }
    },
    "errors": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/error"
      }
    },
    "stats": {
      "type": "object",
      "properties": {
        "total": {
          "type": "integer"
        },
        "results": {
          "type": "integer"
        },
        "errors": {
          "type": "integer"
        },
        "providers": {
          "type": "integer"
        },
        "latency": {
          "type": "integer"
        }
      }
    },
    "found": {
      "type": "boolean"
    }
  }
}

# Example

{
  "datasets": {
    "my-provider": {
      "data": [
        {
          "id": "abc",
          "data": {
            "id": "item-1",
            "title": "Dog"
          },
          "source": {
            "id": "item-1",
            "title": "Dog"
          }
        },
        {
          "id": "def",
          "data": {
            "id": "item-2",
            "title": "Cat"
          },
          "source": {
            "id": "item-2",
            "title": "Cat"
          }
        },
        {
          "id": "ghi",
          "data": {
            "id": "item-3",
            "title": "Mouse"
          },
          "source": {
            "id": "item-3",
            "title": "Mouse"
          }
        }
      ],
      "errors": [],
      "stats": {
        "total": 100,
        "latency": 130
      },
      "found": true
    }
  },
  "errors": [],
  "stats": {
    "total": 100,
    "results": 3,
    "errors": 0,
    "providers": 1,
    "latency": 130
  },
  "found": true
}

# DataView

A shared config schema for several view types, including data and data-multi.

# Properties

As BaseView but with the following additional properties.

Property	Type	Default	Description
media_type	String	application/json	The media (or MIME) type of the response body for this view.
profile	String	n/a (required)	The root profile for this view.
transforms.request	Selector		The glyphs to apply to the incoming HttpDataRequest that yield the DataServiceRequest to be forwarded to the core Rosetta data service.
transforms.response	Selector		The glyphs to apply to the DataServiceResponse that is returned by the core Rosetta data service in order to produce the final response body.

# Example

name: my-view
type: data # May be omitted
paths:
  - /search
  - /get/{id}
  - /resource/{*path}
  - /anything/**
methods:
  - GET
  - POST
media_type: application/json # May be omitted for this value
profile: my-view-profile
transforms:
  request:
    policy: list
    names:
      - my-view-request-transform
  response:
    policy: list
    names:
      - my-view-response-transform

# GetByIdentifierRequest

A standard request model that specifies an identifier and its type only.

# Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "identifier": {
      "type": "string",
      "description": "The identifier of the record to retrieve"
    },
    "identifier_type": {
      "type": "string",
      "description": "The type of the identifier"
    }
  },
  "required": [
    "identifier"
  ],
  "additionalProperties": false
}

# Example

{
  "identifier": "object-123",
  "identifier_type": "system id"
}

# GenericSearchRequest

# Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "queries": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "filters": {
      "type": "object",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "fields": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "autocomplete": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "sort_clauses": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string"
          },
          "direction": {
            "enum": [
              "asc",
              "desc"
            ]
          }
        }
      }
    },
    "aggregations": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "from": {
      "type": "integer"
    },
    "size": {
      "type": "integer"
    }
  }
}

# Example

{
  "queries": [
    "Roman Coin"
  ],
  "ids": [
    "item-123"
  ],
  "filters": {
    "material": [
      "wood",
      "metal"
    ]
  },
  "fields": {
    "title": "Interesting title"
  },
  "autocomplete": {
    "maker": "John"
  },
  "sort_clauses": [
    {
      "path": "name",
      "direction": "asc"
    }
  ],
  "aggregations": [
    "data_type"
  ],
  "from": 0,
  "size": 10
}

# Glyph

A Glyph is an entity that represents a data transformation in Rosetta. Different types of Glyph have different custom properties, but the following properties are common to all Glyph types.

# Properties

Property	Type	Default/Required	Description
name	String	(Required)	The name of the glyph.
type	String	(Required)	The type of the glyph.
properties	Map	null	The custom properties map. This map will be interpreted differently by glyphs of different types.
input	Enum: TransformInputType	current	Determines the type of input used for this glyph. A list of allowed values can be found in the TransformInputType table.
required	Boolean	true	Determines whether the glyph is required. If a glyph is not required, then exceptions that occur while executing the glyph will be caught and appended to the `errors` list in the response. Otherwise, the exception is allowed to cascade upwards, usually resulting in an error response with status code in range 500-599.
priority	Integer	-2^31	The priority of this glyph, a value that determines the default order of glyphs where lower values are executed before higher values.

# TransformInputType

Value	Description
current	If this is the first glyph in a sequence, then the input is the original input object. Otherwise, it is the output of the last glyph in the sequence.
original	The original input object is used as the input for this glyph, regardless of its position in a sequence.
full	A wrapper object known as the 'transform context' is used as the input for this glyph that, at a minimum, includes both current and original versions of the input object. The precise schema of the transform context depends on the phase being executed (request vs. data etc.)

# Example

name: my-glyph
type: elastic-generic-search
properties:
  global_filter: data_type:item
  search_config:
    search_fields:
      - field: _all_fields
      - field: identifier
        boost: 2.0
  path_config:
    paths:
      identifier: identifier.keyword
      name: name.keyword

# HttpDataRequest

# Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "url": {
      "type": "string"
    },
    "host": {
      "type": "string"
    },
    "protocol": {
      "type": "string"
    },
    "scheme": {
      "type": "string"
    },
    "method": {
      "enum": [
        "GET",
        "HEAD",
        "POST",
        "PUT",
        "PATCH",
        "DELETE",
        "OPTIONS",
        "TRACE"
      ]
    },
    "query": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "headers": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "body": {},
    "path": {
      "type": "object",
      "properties": {
        "patterns": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "parameters": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        }
      }
    }
  }
}

# Example

{
  "uri": "/data/item-123",
  "host": "127.0.0.1",
  "protocol": "HTTP/1.1",
  "scheme": "http",
  "method": "GET",
  "query": {
    "q": "John Smith",
    "from": 0,
    "size": 10
  },
  "headers": {
    "content-type": "application/json",
    "host": "localhost:4923"
  },
  "body": {
    "aggs": [
      "data_type",
      "material"
    ],
    "sort": [
      {
        "path": "name",
        "direction": "asc"
      }
    ]
  },
  "path": {
    "patterns": [
      "/data/{id}"
    ],
    "parameters": {
      "id": "item-123"
    }
  }
}

# HttpRequestMethod

An enum representing HTTP request methods.

# Values

Value
GET
HEAD
POST
PUT
PATCH
DELETE
OPTIONS
TRACE

# Metadata

The internal representation of a result retrieved by the Rosetta data service.

# Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The internal identifier of this result. Can be populated in the domain phase of a Profile."
    },
    "data": {
      "description": "The current representation of this result. May take any form. Will be the same as the 'source' field if no transforms are configured."
    },
    "source": {
      "description": "The original representation of this result as retrieved by the Provider or as determined by the domain phase if used."
    }
  }
}

# Example

{
  "id": "object-123",
  "data": {
    "id": "object-123",
    "title": "An Informative Title",
    "description": "A descriptive description"
  },
  "source": {
    "id": "object-123",
    "title": "An Informative Title",
    "description": "A descriptive description"
  }
}

# Profile

A Profile is an entity that is used to coordinate the dataflow of a Rosetta data service request. It specifies the providers and transforms to be used in a Rosetta data request and determines the set of profiles allowed for a given endpoint or view.

# Properties

Property	Type	Default/Required	Description
name	String	(Required)	The name of the profile.
profiles	Selector	`policy: none`	A selector specifying the allowed profiles when this profile is used as a root profile for an endpoint or view.
providers	Selector	`policy: none`	A selector specifying the providers to be used for this profile.
transforms.request	TransformStage[]	`[]`	A list of transform stages to apply at the request phase.
transforms.provider	TransformStage[]	`[]`	A list of transform stages to apply at the provider phase.
transforms.domain	TransformStage[]	`[]`	A list of transform stages to apply at the domain phase.
transforms.data	TransformStage[]	`[]`	A list of transform stages to apply at the data phase.

# TransformStage

Property	Type	Default	Description
glyphs	Selector	`policy: none`	A selector specifying the glyphs to be used in this transform stage.
criteria.providers	Selector	`policy: all`	The glyphs specified in this transform stage will only be applied to the providers specified in this selector.

# Examples

Simple example

name: my-profile
providers:
  policy: list
  names:
    - my-provider
transforms:
  request:
    - glyphs:
        policy: list
        names:
          - request-transform
  data:
    - glyphs:
        policy: list
        names:
          - data-transform

Complex example

name: my-profile
profiles:
  policy: exclude
  names:
    - not-this-profile
providers:
  policy: include
  names:
    - provider-a
    - provider-b
transforms:
  request:
    - criteria:
        providers:
          policy: include
          names:
            - provider-a
      glyphs:
        policy: list
        names:
          - request-transform-for-provider-a
    - criteria:
        providers:
          policy: include
          names:
            - provider-b
      glyphs:
        policy: list
        names:
          - request-transform-for-provider-b
  provider:
    - glyphs:
        policy: list
        names:
          - provider-transform
  domain:
    - glyphs:
        policy: list
        names:
          - domain-transform
  data:
    - glyphs:
        policy: list
        names:
          - data-transform-1
          - data-transform-2

# Provider

A Provider is an entity that represents a provider of data (or a data source) in Rosetta. Different provider types have different custom properties, but the following properties are common to all provider types.

# Properties

Property	Type	Default/Required	Description
name	String	(Required)	The name of the provider.
type	String	(Required)	The type of the provider.
properties	Map	null	The custom properties map. This map will be interpreted differently by providers of different types.
enabled	Boolean	true	Determines whether the provider is enabled. A disabled provider will be ignored when executing a data service request, even if it is included in the profile.

# Example

name: my-provider
type: elasticsearch
properties:
  protocol: http
  host: localhost
  port: 9200
  index: my-index

# Selector

A selector specifies a subset of a set of (possibly ordered) named entities or data structures.

# Properties

Property	Type	Required	Description
policy	Enum (SelectorPolicy)	Yes	The policy to be used in this selector. See SelectorPolicy for description of allowed values.
Names	String[]	No	The names to be used as parameters for certain selector policies.

# SelectorPolicy

Policy	Uses names	Description
none	No	Selects no items.
all	No	Selects all items.
list	Yes	Selects only the items whose names are in the `names` list, in the order specified in the `names` list.
include	Yes	Selects only the items whose names are in the `names` list, in default order (usually determined by the `priority` of the items being selected).
exclude	Yes	Selects only the items whose names are not in the `names` list, in default order (usually determined by the `priority` of the items being selected).

# Example

policy: list
names:
  - first-item
  - second-item
  - third-item

# SimpleDataResponse

# Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {}
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "cause": {
            "type": "string"
          }
        }
      }
    },
    "stats": {
      "type": "object",
      "properties": {
        "total": {
          "type": "integer"
        },
        "results": {
          "type": "integer"
        },
        "errors": {
          "type": "integer"
        },
        "providers": {
          "type": "integer"
        },
        "latency": {
          "type": "integer"
        }
      }
    },
    "found": {
      "type": "boolean"
    }
  }
}

# Example

{
  "data": [
    {
      "id": "item-1",
      "title": "Dog"
    },
    {
      "id": "item-2",
      "title": "Cat"
    },
    {
      "id": "item-3",
      "title": "Mouse"
    }
  ],
  "errors": [],
  "stats": {
    "total": 100,
    "results": 3,
    "errors": 0,
    "providers": 1,
    "latency": 130
  },
  "found": true
}

# View

A View is a configurable REST API endpoint in Rosetta.

# Properties

Each type of View defines its own configuration schema. See the Entity Reference and plugins pages for individual View types.