# Declarative metadata structure (IRPCDeclarativeMetadataStructure)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/

Reads and validates the whole metadata structure of a vault as one declarative JSON document.
Preview feature, off by default.

- **gRPC service:** `MFiles.IRPCDeclarativeMetadataStructure`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 8
- **Proto file:** [`mfiles/IRPCDeclarativeMetadataStructure.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCDeclarativeMetadataStructure.proto)

<a id="overview"></a>

## Overview

**Not available by default.** The declarative metadata structure is a preview feature. On a
server where it is not enabled, every method fails with "Not implemented." (gRPC status
`UNKNOWN`, error code 0x80004001) before any rights check.
[SetDeclarativeMetadataStructureBeginSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureBeginSession/index.md),
[SetDeclarativeMetadataStructureEndSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureEndSession/index.md)
and
[NewDeclarativeMetadataStructureRevisionAvailable](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/NewDeclarativeMetadataStructureRevisionAvailable/index.md)
are not implemented even when the feature is on.

**The declarative format.** A declarative metadata structure document is a JSON text that
describes the vault's object types, value lists, classes, class groups, property definitions,
workflows and named access control lists, with the users, user groups and value list items they
refer to. Elements refer to each other **by name**, not by vault-specific ID, so the document can
be read, compared and edited by people and tools. Property names are camelCase and enumerations
are strings. The document also carries `schemaVersion`, `writerInfo`, and the structure's
`revision` (positive: a revision from the declarative configuration service; negative: a
revision made locally on this server, with `revisionBase` naming the revision it is based on).
[GenerateDeclarativeMetadataStructureSchema](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/GenerateDeclarativeMetadataStructureSchema/index.md)
returns the JSON Schema of the format.

**How the two services relate.**
[IRPCDeclarativeMetadataStructureAsProtobuf](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/index.md)
exchanges the same structure as a typed
[DeclarativeMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DeclarativeMetadataStructure/index.md) message that uses the
vault's IDs. This service exchanges the declarative JSON document as a string. The server
converts between the two with the declarative configuration converter that is installed with
M-Files Server:
[GetDeclarativeMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/GetDeclarativeMetadataStructure/index.md)
builds the typed structure and converts it to JSON;
[SetDeclarativeMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructure/index.md)
validates or converts JSON in the other direction.

- **Session and rights.** Every method requires a vault session and the vault right
  `change_metadata_structure`, reads included.
- **Who calls it.** Declarative configuration tooling for M-Files. Applications should read the
  structure with the Vault API ([IRPCObjectTypes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/index.md),
  [IRPCPropertyDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/index.md)) and should not call this service.
- **Revision generation.** When this feature is on, every local structure change makes the server
  generate a new revision of the declarative structure.
  [PauseDeclarativeMetadataStructureRevisionGeneration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/PauseDeclarativeMetadataStructureRevisionGeneration/index.md)
  lets one session make a batch of changes with one catch-up revision at the end.
- Every method sends the `mfiles-metadata-version-bin` trailer when it succeeds.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [CancelDeclarativeMetadataStructureRevisionGenerationPause](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/CancelDeclarativeMetadataStructureRevisionGenerationPause/index.md) | Ends the calling session's pause of automatic revision generation. | `admin` `session` `returns metadata structure version` |
| [GenerateDeclarativeMetadataStructureSchema](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/GenerateDeclarativeMetadataStructureSchema/index.md) | Gets the JSON Schema document that describes the declarative metadata structure format. | `admin` `session` `returns metadata structure version` |
| [GetDeclarativeMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/GetDeclarativeMetadataStructure/index.md) | Gets the vault's current metadata structure as a declarative JSON document. | `admin` `session` `returns metadata structure version` |
| [NewDeclarativeMetadataStructureRevisionAvailable](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/NewDeclarativeMetadataStructureRevisionAvailable/index.md) | Reserved for telling the server that a new structure revision is available. Not implemented. | `admin` `session` `returns metadata structure version` |
| [PauseDeclarativeMetadataStructureRevisionGeneration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/PauseDeclarativeMetadataStructureRevisionGeneration/index.md) | Starts, extends or reads a pause of automatic revision generation for the calling session. | `admin` `session` `returns metadata structure version` |
| [SetDeclarativeMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructure/index.md) | Validates a declarative JSON document against the schema, or converts it for deployment. | `admin` `session` `returns metadata structure version` |
| [SetDeclarativeMetadataStructureBeginSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureBeginSession/index.md) | Reserved for setting a structure in several parts. Not implemented. | `admin` `session` `returns metadata structure version` |
| [SetDeclarativeMetadataStructureEndSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureEndSession/index.md) | Reserved for setting a structure in several parts. Not implemented. | `admin` `session` `returns metadata structure version` |