# Naming Query Templates

*Convention, non-normative. The service enforces only the grammar of a name (see the reference,
chapter 10, Query Templates, and chapter 12, Naming Conventions); this page describes the
convention the components of the infrastructure follow on top of it.*

## The rule

The name of a Query Template starts with the **macro-group** that owns it, followed by what the
template returns:

```
<macro-group>-[all-]<object>[-by-<criteria>]
```

- No verb: a Query Template is always a read, so `get` says nothing.
- `all-` marks the complete list of a type, with no criteria narrowing it:
  `catalogue-all-metadata-profiles`, `is-all-eservice`.
- `-by-<criteria>` marks a lookup narrowed by its variables. The object is singular when the intent
  is one resource (even if several equal copies may answer, e.g. the `EService` of a service
  deployed twice) and plural when the intent is a set: `gcube-eservice-accesspoint-by-group-and-name`,
  `gcube-eservices-by-state`.
- Neither of them: the one resource of its kind in the Context, with no variables:
  `catalogue-configuration`.
The whole name stays inside the grammar of the service: lowercase words separated by hyphens,
`^[a-z][a-z0-9]*(-[a-z0-9]+)*$`.

The name says who maintains the template and what it looks for, nothing more. The technology behind
a resource does not enter the name: when it changes, a new `version` of the definition follows it
and the name stays. Every other property of the answer, a projection first of all, is said by the
description.

## The description

The `description` is mandatory and it is what a caller reads to know what the template returns:

- it starts with `Returns` and names the type of the instances returned, with the criteria the
  variables apply;
- when the template projects the result with `_emit`, it says so and lists the fields returned
  (`Projection: ...`): the caller receives those fields, not the instances;
- it does not describe the request body or the default values of the variables: each variable has
  its own description, and the default value of a variable only lets the service test the query.

## Macro-groups

| Prefix | Owner | Components |
|---|---|---|
| `catalogue-` | the catalogue stack | gcat, catalogue-core, gcat-client, grsf-publisher, the gcat plugins |
| `accounting-` | the accounting stack | accounting libraries and services, aggregator, dashboard harvester |
| `is-` | the Information System stack | queries of the IS tools themselves, e.g. the lists by Type of the IS GUI |
| `gcube-` | gcube-model, which defines the Types these queries read | generic queries offered to every gCube service and tool (the IS GUI among them) so that none writes them again: the base ones on relations and facets of any resource, and the ones on the gCube model (`EService`, `SoftwareFacet`, `AccessPointFacet`, ...) |
| `uri-resolver-` | the URI Resolver stack | uri-resolver, uri-resolver-manager, gcube-url-shortener |
| `provisioning-` | the provisioning | queries that only the provisioning (the Ansible playbooks and the collection `gcube.resource_registry`) needs |

A new macro-group is added here when a new stack defines its first template.

## Why the macro-group and not the component

- **Shared libraries.** Many templates are installed and run by a library shared by several
  services (catalogue-core runs in gcat and in grsf-publisher). The macro-group names them without
  choosing one service as their owner.
- **Stable names.** A function that moves from a service to its library, or a new service of the
  same stack, keeps the name of its templates.
- **Grouped listings.** Sorted by name, the templates of a stack are listed together.
- **Generic queries are not owned by their first user.** A query that any service could use
  (`is-` or `gcube-`) keeps the generic prefix even when a single component installs it or runs it
  today.
- **Clear ownership.** The prefix tells which stack maintains the template and raises its
  `version` when its definition changes.

## Changing a name

A Query Template is never renamed: the template with the new name is created at version `1.0.0`
and the one with the old name is deleted once no client runs it any more.

## Who installs a template

- A service or a library installs the templates it runs at start-up, with its own token, through
  the versioned upsert (`PUT /query-templates/{name}`): the same definition is a no-op, a higher
  `version` updates it, and a `409 Conflict` tells an outdated component that a newer definition is
  already installed.
- The provisioning installs its templates with the token of the provisioning client.
- The generic templates (`gcube-`) and the ones of the IS tools (`is-`) are part of the reference
  set installed by the Resource Registry migration.

The token that installs a template needs a role allowed to write Query Templates (`IS-Manager`,
`Infrastructure-Manager` or `IS-Admin`). The registry records the identity that created a template
in its metadata: together with the prefix, it tells who put it there and why.
