// M-Files Server gRPC API 26.11. Generated from the M-Files Server IDL; do not edit.
// Documentation: https://developer.m-files.com/APIs/gRPC-API/
syntax = "proto3";

package MFiles;

import "mfiles/api/annotations.proto";

option csharp_namespace = "MFiles.Grpc";
option go_package = "github.com/M-Files/mfiles-grpc-api/go/mfiles;mfiles";
option java_multiple_files = true;
option java_package = "com.mfiles.grpc";
option objc_class_prefix = "MF_";

// Reads and validates the whole metadata structure of a vault as one declarative JSON document.
// Preview feature, off by default.
//
// **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](mfiles:MFiles.IRPCDeclarativeMetadataStructure.SetDeclarativeMetadataStructureBeginSession),
// [SetDeclarativeMetadataStructureEndSession](mfiles:MFiles.IRPCDeclarativeMetadataStructure.SetDeclarativeMetadataStructureEndSession)
// and
// [NewDeclarativeMetadataStructureRevisionAvailable](mfiles:MFiles.IRPCDeclarativeMetadataStructure.NewDeclarativeMetadataStructureRevisionAvailable)
// 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](mfiles:MFiles.IRPCDeclarativeMetadataStructure.GenerateDeclarativeMetadataStructureSchema)
// returns the JSON Schema of the format.
//
// **How the two services relate.**
// [IRPCDeclarativeMetadataStructureAsProtobuf](mfiles:MFiles.IRPCDeclarativeMetadataStructureAsProtobuf)
// exchanges the same structure as a typed
// [DeclarativeMetadataStructure](mfiles:MFiles.DeclarativeMetadataStructure) 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](mfiles:MFiles.IRPCDeclarativeMetadataStructure.GetDeclarativeMetadataStructure)
// builds the typed structure and converts it to JSON;
// [SetDeclarativeMetadataStructure](mfiles:MFiles.IRPCDeclarativeMetadataStructure.SetDeclarativeMetadataStructure)
// 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](mfiles:MFiles.IRPCObjectTypes),
//   [IRPCPropertyDefs](mfiles:MFiles.IRPCPropertyDefs)) 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](mfiles:MFiles.IRPCDeclarativeMetadataStructure.PauseDeclarativeMetadataStructureRevisionGeneration)
//   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.
service IRPCDeclarativeMetadataStructure {
	option (mfiles.api.service) = { book: "admin" level: LEVEL_SPECIALIZED title: "Declarative metadata structure" };

	// Gets the vault's current metadata structure as a declarative JSON document.
	//
	// - Fails with "Not implemented." unless the feature is enabled on the server.
	// - Requires `change_metadata_structure`.
	// - Always returns the current structure: the server does not read `revision`.
	// - The conversion runs in a separate converter process on the server, with a one-minute limit.
	rpc GetDeclarativeMetadataStructure( GetDeclarativeMetadataStructureRequest ) returns ( GetDeclarativeMetadataStructureResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Validates a declarative JSON document against the schema, or converts it for deployment.
	//
	// - Fails with "Not implemented." unless deploying declarative structures is enabled on the server.
	// - Requires `change_metadata_structure`.
	// - With `dry_run_with_schema_validation` true, nothing changes: `validated` is true and
	//   `validation_errors` lists the schema violations (empty when the document is valid).
	// - With `dry_run_with_schema_validation` false, the server converts the document but, in this
	//   server version, does not apply the result to the vault.
	// - `session` is not used; the begin and end session methods are not implemented.
	rpc SetDeclarativeMetadataStructure( SetDeclarativeMetadataStructureRequest ) returns ( SetDeclarativeMetadataStructureResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Reserved for setting a structure in several parts. Not implemented.
	//
	// - Always fails with "Not implemented.", whether or not the feature is enabled.
	rpc SetDeclarativeMetadataStructureBeginSession( SetDeclarativeMetadataStructureBeginSessionRequest ) returns ( SetDeclarativeMetadataStructureBeginSessionResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Reserved for setting a structure in several parts. Not implemented.
	//
	// - Always fails with "Not implemented.", whether or not the feature is enabled.
	rpc SetDeclarativeMetadataStructureEndSession( SetDeclarativeMetadataStructureEndSessionRequest ) returns ( SetDeclarativeMetadataStructureEndSessionResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Gets the JSON Schema document that describes the declarative metadata structure format.
	//
	// - Fails with "Not implemented." unless the feature is enabled on the server.
	// - Requires `change_metadata_structure`. Changes nothing.
	// - Validate a document against this schema locally, or on the server with
	//   [SetDeclarativeMetadataStructure](mfiles:MFiles.IRPCDeclarativeMetadataStructure.SetDeclarativeMetadataStructure)
	//   and `dry_run_with_schema_validation`.
	rpc GenerateDeclarativeMetadataStructureSchema( GenerateDeclarativeMetadataStructureSchemaRequest ) returns ( GenerateDeclarativeMetadataStructureSchemaResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Reserved for telling the server that a new structure revision is available. Not implemented.
	//
	// - Always fails with "Not implemented.", whether or not the feature is enabled.
	rpc NewDeclarativeMetadataStructureRevisionAvailable( NewDeclarativeMetadataStructureRevisionAvailableRequest ) returns ( NewDeclarativeMetadataStructureRevisionAvailableResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Starts, extends or reads a pause of automatic revision generation for the calling session.
	//
	// While the pause is active, structure changes made by this session do not each generate a new
	// revision of the declarative metadata structure. When the pause ends, by
	// [CancelDeclarativeMetadataStructureRevisionGenerationPause](mfiles:MFiles.IRPCDeclarativeMetadataStructure.CancelDeclarativeMetadataStructureRevisionGenerationPause)
	// or by expiry, the server generates one catch-up revision.
	//
	// - Fails with "Not implemented." unless local revision generation is enabled on the server.
	// - Requires `change_metadata_structure`.
	// - A positive `duration_seconds` starts a pause, or extends this session's pause (never shortens
	//   it). 0 only reads the remaining time and changes nothing. A negative value or more than 3600
	//   fails with an invalid-argument error.
	// - Each session has at most one pause, identified by the session itself; other sessions are not
	//   affected.
	rpc PauseDeclarativeMetadataStructureRevisionGeneration( PauseDeclarativeMetadataStructureRevisionGenerationRequest ) returns ( PauseDeclarativeMetadataStructureRevisionGenerationResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Ends the calling session's pause of automatic revision generation.
	//
	// - Fails with "Not implemented." unless local revision generation is enabled on the server.
	// - Requires `change_metadata_structure`.
	// - Ending an active pause makes the server generate the catch-up revision if one is needed.
	// - Succeeds without effect when the session has no active pause.
	rpc CancelDeclarativeMetadataStructureRevisionGenerationPause( CancelDeclarativeMetadataStructureRevisionGenerationPauseRequest ) returns ( CancelDeclarativeMetadataStructureRevisionGenerationPauseResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}
}

// The request of GetDeclarativeMetadataStructure.
message GetDeclarativeMetadataStructureRequest {

	// Not used by the server; the current structure is returned.
	int32 revision = 1;
}

// The response of GetDeclarativeMetadataStructure.
message GetDeclarativeMetadataStructureResponse {

	// The declarative metadata structure document (JSON text). Its format is described by [GenerateDeclarativeMetadataStructureSchema](mfiles:MFiles.IRPCDeclarativeMetadataStructure.GenerateDeclarativeMetadataStructureSchema).
	string declmds = 1;
}

// The request of SetDeclarativeMetadataStructure.
message SetDeclarativeMetadataStructureRequest {

	// Not used by the server. Leave 0.
	uint32 session = 1;

	// The declarative metadata structure document, as returned by [GetDeclarativeMetadataStructure](mfiles:MFiles.IRPCDeclarativeMetadataStructure.GetDeclarativeMetadataStructure).
	string declmds_as_json = 2;

	// True to only validate the document against the schema.
	bool dry_run_with_schema_validation = 3;
}

// The response of SetDeclarativeMetadataStructure.
message SetDeclarativeMetadataStructureResponse {

	// True when the call was a dry run.
	bool validated = 1;

	// The schema validation errors as text, empty if the document is valid. Set only when `validated` is true.
	string validation_errors = 2;
}

// The request of SetDeclarativeMetadataStructureBeginSession.
message SetDeclarativeMetadataStructureBeginSessionRequest {
}

// The response of SetDeclarativeMetadataStructureBeginSession.
message SetDeclarativeMetadataStructureBeginSessionResponse {

	// Session identifier.
	uint32 session = 1;
}

// The request of SetDeclarativeMetadataStructureEndSession.
message SetDeclarativeMetadataStructureEndSessionRequest {

	// Session identifier.
	uint32 session = 1;

	// True to commit the Set operation.
	bool commit = 2;

	// Reserved. Ignored when `commit` is false.
	bool dry_run_with_schema_validation = 3;
}

// The response of SetDeclarativeMetadataStructureEndSession.
message SetDeclarativeMetadataStructureEndSessionResponse {

	// True for dry runs with schema validation.
	bool validated = 1;

	// Reserved. Set only when `validated` is true.
	string validation_errors = 2;
}

// The request of GenerateDeclarativeMetadataStructureSchema.
message GenerateDeclarativeMetadataStructureSchemaRequest {
}

// The response of GenerateDeclarativeMetadataStructureSchema.
message GenerateDeclarativeMetadataStructureSchemaResponse {

	// The JSON Schema of the declarative metadata structure document, as text.
	string declmds_schema = 1;
}

// The request of NewDeclarativeMetadataStructureRevisionAvailable.
message NewDeclarativeMetadataStructureRevisionAvailableRequest {
}

// The response of NewDeclarativeMetadataStructureRevisionAvailable.
message NewDeclarativeMetadataStructureRevisionAvailableResponse {
}

// The request of PauseDeclarativeMetadataStructureRevisionGeneration.
message PauseDeclarativeMetadataStructureRevisionGenerationRequest {

	// The pause length in seconds, 1 to 3600, or 0 to read the status only.
	int32 duration_seconds = 1;
}

// The response of PauseDeclarativeMetadataStructureRevisionGeneration.
message PauseDeclarativeMetadataStructureRevisionGenerationResponse {

	// Seconds left on this session's pause, rounded up. 0 means no active pause.
	int32 remaining_seconds = 1;
}

// The request of CancelDeclarativeMetadataStructureRevisionGenerationPause.
message CancelDeclarativeMetadataStructureRevisionGenerationPauseRequest {
}

// The response of CancelDeclarativeMetadataStructureRevisionGenerationPause.
message CancelDeclarativeMetadataStructureRevisionGenerationPauseResponse {

	// Seconds left on this session's pause after the call; normally 0.
	int32 remaining_seconds = 1;
}