# Rosetta Entities

# Entity types

The following table lists all available Rosetta entities, their location in the Rosetta config YAML and their types.

Name	Rosetta Entity Class	Location in Rosetta Config	Entry Type
Proteus Glyph	Glyph	`rosetta.transform.glyphs[]`	`proteus`
Proteus Provider (Simple)	Provider	`rosetta.provider.providers[]`	`proteus-simple`
Proteus Provider (Cached file)	Provider	`rosetta.provider.providers[]`	`proteus-cached-file`
Custom Type Repository (File)	CustomTypeRepository	`rosetta.plugins.proteus.repository.repositories[]`	`file`

# Provider (Cached file)

The Cached File Proteus Provider is a specialised version of the Simple Proteus Provider that can be used to improve performance when the data is coming from very large files.

On the first request, it caches the entire provider result set in memory, then a subset of the cached data can be retrieved in subsequent requests using the paging request parameters from and size.

The cache is automatically cleared after a period of access inactivity, or if the file located at file in the config properties is modified.

# Custom Type Repository (File)

Custom type repositories allow custom components to be defined as Proteus spec snippets, which are each associated with a type name. A custom component can then be invoked by specifying its type name in the #type field of a component spec.

The file custom type repository allows a base file path to be specified, and if this path points to a directory, then all readable json files within this directory will be scanned and registered against a type name derived either from its file path or from a top-level key within the JSON definition.

See Entity Config for further details on how to configure a custom type repository.

# Config Properties

# Proteus Config

The following table lists all properties available to a Proteus Config object, which can be considered a (de)serializable version of the Config object. Proteus Config objects are used in multiple areas of the overall config such as Rosetta entities and the POST /proteus/transform API endpoint.

Name	Type	Required	Default	Description
properties	Map	no	n/a	A map used to populate the `properties` map for this transform
path_not_found_to_null	Boolean	no	true	If true, an unresolved atomic path will resolve to null. Otherwise, an exception is thrown.
unbox_singletons	Boolean	no	true	If true, atomic paths that resolve to singleton lists will be automatically unboxed and the result will be the sole element of that list. Otherwise, the list will be passed through unchanged.
reader_cache_max_size	Integer	no	100	Sets the maximum size for the `ObjectReader` cache.
type_registries	List	no	["$.type_registry"]	List of JSONPath strings that navigate to type registry maps within the arguments or properties map.
http_client	Enum	no	ok_http	Selects the HTTP client used in `http_request` components. Can be one of `ok_http`, `java` or `disallowed` for the OkHttp client, Java client or to disallow all HTTP requests, respectively.
accumulator	Enum	no	disallowed	Selects the default accumulator to use with `as_value`, map untyped specs or when attempting to reduce for a singular component parameter. Can be one of `first`, `last` or `disallowed` for selecting the first element, last element or to throw an exception, respectively.
cache	String	no	n/a	Sets the name of the cache to be retrieved from the `CacheManager` and used in the entity's `CacheProvider`.
encryption_provider	Enum	no	disallowed	The name of the encryption provider to use. Allowed values are `disallowed` or `java_aes`.
encryption_salt	String	no (yes if `encryption_provider` is set to `java_aes`)	n/a	The encryption salt used when generating encryption keys from plaintext passwords.
enable_file_read	Boolean	no	false	Enables file read operations (required for `file_read` and `file_details` components).
enable_file_write	Boolean	no	false	Enables file write operations (required for `file_write` component).
enable_file_delete	Boolean	no	false	Enables file delete operations (required for `file_delete` component).
enable_id_generator	Boolean	no	false	Enables a Proteus `IdGenerator` that wraps the Spring `IdGenerator` provided by the `ApplicationContext` (configured in Rosetta).

# Plugin Properties

The following table lists all properties that are specific to the Proteus Rosetta plugin.

Name	Path	Type	Required	Default	Description
api	`rosetta.plugins.proteus.api`	Proteus Config	no	n/a	The Proteus Config object to use with the `POST /proteus/transform` endpoint. This is merged with the config provided in the request before the spec is resolved.
repositories	`rosetta.plugins.proteus.repository.repositories[]`	Array	no	n/a	A list of config objects that define the available custom type repositories. See Entity Config for the list of properties available to each custom type repository entry.
global_repositories	`rosetta.plugins.proteus.repository.global_repositories`	Selector	no	n/a	A selector that determines which custom type repositories are globally available to all Proteus entities

# Entity Config

The following table lists all properties available to Rosetta entities. If a property is only applicable to a specific type of Rosetta entity, then applicable entity types are listed the column Entity. Note that all property paths are relative to the entry within their respective entity list. E.g. for Glyphs the full path for the property spec will be rosetta.transform.glyphs[].properties.spec.

See table in Entity types section for details on entity list locations.

Name	Path	Type	Required	Default	Entity	Description
name	`name`	String	yes	n/a	All	The entity's name. This is arbitrary but should be unique
type	`type`	String	yes	n/a	All	This should be set to `proteus` for all entities
spec	`properties.spec`	String	yes	n/a	Glyph, Provider	File path to the spec JSON file
config	`properties.config`	Proteus Config	no	n/a	Glyph, Provider	The Proteus config object to use with this entity
mutable	`properties.mutable`	Boolean	no	false (true for type repositories)	Glyph, Provider, Custom Type Repository	Iff true, the spec will be reloaded at request time if its timestamp has changed
include	`properties.include`	Array	no	n/a	Glyph, Provider	A list of file paths to JSON objects that are used to populate the properties map for this transform
repositories	`properties.repositories`	Selector	no	n/a	Glyph, Provider	Selects the custom type repositories to use with this entity
log_missing_paths	`properties.log_missing_paths`	Boolean	no	false	Glyph, Provider	If true, a message will be logged at trace level whenever a JSONPath fails to resolve.
file	`properties.file`	String	yes	n/a	Provider (Cached file)	Path to a file whose last modified date invalidates the cached provider response when it changes.
path	`properties.path`	String	yes	n/a	Custom Type Repository (File)	The base file path for the custom type repository. May be either a file or directory. If a directory, a recursive scan is performed filtering only readable files with 'json' as the extension
shape	`properties.shape`	Shape	no	`root`	Custom Type Repository (File)	The shape of each type definition file (see the Shape table for list of accepted values)
depth	`properties.depth`	Integer	no	2^31 - 1	Custom Type Repository (File)	The recursion depth of the directory scan.
name_mode	`properties.name_mode`	Name Mode	no	`base_name`	Custom Type Repository (File)	The `#type` name mode to be used when the `shape` property is equal to `root` (see Name Mode list of accepted values).
namespace	`properties.namespace`	String	no	n/a	Custom Type Repository (File)	A namespace prefix prepended to each `#type` name joined by the namespace separator.
namespace_separator	`properties.namespace_separator`	String	no	`/`	Custom Type Repository (File)	The namespace separator (see `namespace` above)
min_refresh_duration	`properties.min_refresh_duration`	Duration	no	`1s`	Custom Type Repository (File)	Minimum duration between subsequent refresh checks. Only used when `mutable` is set to `true`.

# Shape

Value	Description
`root`	The whole file is considered a single type definition. The file path and name mode determines the `#type` name.
`map`	The file is read as a top-level map of type definitions where the keys define the `#type` names.

# Name Mode

Value	Description
`base_name`	The base file name is used as the `#type` name. E.g. `/path/to/type_definition.json` becomes `type_definition`.
`relative_path`	The base file name prefixed by the path relative to the repository root is used as the `#type` name. E.g. `/path/to/type_definition.json` becomes `path/to/type_definition`.

rosetta