METADATA.ini

#
# SpecElektra is a specification language that describes content
# of KDB (the global key database).
#
# Put simply, SpecElektra (i.e. configuration in the spec: namespace)
# allows you to describe how the configuration of the system looks
# like. For example, it allows you to describe which configuration
# files in which formats are present on the system.
#
# SpecElektra does not have built-in keywords, instead it is
# completely extensible by metadata interpreted by Elektra's plugins.
#
# Any of Elektra's supported configuration formats that are able
# to write metadata can be used for SpecElektra.
#


#
# This document describes all metadata and specification values available
# in SpecElektra.
#
# If your plugin/tool/API uses metadata, please add it here.
#
# Some parts of this file are already used by tools:
#
# 1. It can be mounted with the ni plugin, see scripts/mount-info
# 2. It is checked for consistency with contracts of plugins, see
#    tests/shell/check_meta.sh
#

#
# METADATA.ini meta-specification (description how to parse/use this file):
#
# [the name of the metakey]
# type = (<CORBA type>|enum <enum>|regex <regular expression>) the type of the metavalue
# status = (implemented|proposed|idea|deprecated|unclear) the current state of this metadata entry
# usedby/api = the API methods which use the metakey (space separated)
# usedby/plugin = the plugins which use the metakey (space separated)
# usedby/tool = the tools which use the metakey (space separated)
# description = explains what the metadata is about
# note = give additional notes for that metakey
# example = give additional examples how the metakey might look like
#
# Nearly all of the metadata is automatically used by `spec-mount` thus
# `spec-mount` is not listed in usedby/tool.
#
#
#
# To mount this file you can use:
#
#  kdb mount-info
#
# and keys will be below:
#
#  kdb export system:/info/elektra/metadata/#0
#
# for example, to get the type of type:
#
#  kdb meta-get system:/info/elektra/metadata/#0/type type
#
# Note that the ni plugin does not preserve comments nor order,
# so it is not suitable to write to this file.
#


[]
filename = METADATA.ini
version/major = 0
version/minor = 6


#
# Important metadata often used in configuration files
# and not used in specifications.
#

[order]
type = long
status = implemented
usedby/plugin = hosts augeas toml
usedby/api = elektraKeyCmpOrder
description = "Relative order in the KeySet if non-alphabetical order
	is needed. This metadata is only to preserve order as found in
	the file. It is an hint to allow complete reconstruction as it
	was before.
	
	Keys without order metadata or keys with same order, yield
	implementation-defined ordering.
	
	When some knowledge about desired ordering exists, e.g. when
	key sets are merged, the keys should to be reordered to avoid
	this."
note = "This will rarely used within specifications, but is directly
	derived from configuration files.
	
	I.e. only storage plugins set and get this property."

[comment/#]
status = implemented
usedby/plugin = hosts
type = string
description = "A comment preceding or in-line with a key.

	- #0 is the inline comment (in the same line).
	- The comment numbering starts from top (#1) to bottom (#n).
	- The comment directly above the key is the last entry in the array (#n).
	- The topmost comment belonging to the key is (#1).

	Comment keys that are not above any key (comments in the last
	lines of files) are added to the parentkey.

	The array of comments allows:

	- to structure comments, which are not line-based
	- to restore formatting, including:
	 - inline comments
	 - spaces before comments
	 - empty lines
	- to distinguish between different kinds of comments
	- to tag every comment, which increases extensibility

	The plugin need to take care that only valid characters are
	present in the comment.
	E.g. on line-based comments, no newlines must be present."
note = "If used within specifications it refers to the specification, not
	the key. Use `description` to refer to the key."

[comment/#/start]
status= implemented
usedby/plugin= hosts
type= string
description= "Determines the character(s) used to start this comment.

	This metakey is empty if its an empty line/comment.

	The default on absence of this key is plugin-specific.
	Some comment start character should be assumed then.

	The plugin needs to make sure that every comment is actually
	commented out. An error needs to be emitted if there is no
	start symbol that will be recognized as comment."
example= ;

[comment/#/space]
status= implemented
usedby/plugin= hosts
type= string
description="The spaces/tabs used between a comment and the beginning of the
	line or after end of payload data (for inline comments).

	If no start key is present, only space and no comment is present.

	The plugin needs to make sure that all spaces present are allowed.
	An error needs to be emitted if non-ignored spaces are present."
example=


[internal/<plugin>/*]
status= implemented
usedby/plugin=
description="Internal metadata that must be ignored by other plugins.
	It is useful for reconstruction of information about keys between
	kdbGet and kdbSet.
	Always avoid to use it if there is any other metadata that
	can be used instead.
	For example, if a type can be represented with the CORBA
	type system, metadata `type` should be used.
	Only if a type cannot be represented, e.g., the `toml`
	plugin would use `internal/toml/type`."



#
# Needed for specification of key access (ksLookup by spec)
#

[fallback/#]
type=key name
status=implemented
usedby/api= ksLookup
description="When a key was looked up unsuccessfully, keys in this
	array will be tried instead."

[override/#]
type=key name
usedby/api= ksLookup
status=implemented
description=Keys in this array will be preferred over the key itself

[namespace/#]
type=namespace
status=implemented
usedby/api= ksLookup
description="Typically all namespaces are cascaded one after the other
	in the built-in order.
	Using this metadata you can avoid that some namespaces are used or
	can change the order."

[default]
usedby/tool = ksLookup web
status = implemented
usedby/api = ksLookup
description = "The default value will be used if no other value could
	be found.
	
	Make sure for your application that the default is sane and secure."




[context]
status=implemented
usedby/api=getenv
description="use /env/layer and internal information to facilitate
	a context-aware lookup"


[callback/_]
status=reserved
usedby/tool=kdb
usedby/api=getenv
description="reserved meta information that will be preserved during the whole
	chain of ksLookup() callback calls"


#
# Basic information about keys
#

[type]
type= "enum
	short
	unsigned_short
	long
	unsigned_long
	long_long
	unsigned_long_long
	float
	double
	long_double
	char
	boolean
	octet
	any
	string"
status= implemented
usedby/plugin= range type
description="Defines the type of the value, as specified in CORBA
	Unlike check/type, type is also used for code generation and within the APIs.
	The range plugin uses type as fallback, if check/type is not specified."
example= any


[array]
type = array-index
status = implemented
description = "Array keys have only keys conforming to Elektra’s arrays convention as subkeys.
	
	Within specifications, it means that the key is an array.
	
	Outside of specifications:
	If the metavalue is empty, the array is empty (no subkeys).
	Otherwise the metavalue contains the last element.
	
	See also doc/tutorials/arrays.md"
example = #5





#
# Needed for mounting by specification
#

[mountpoint]
type = string
status = implemented
usedby/tool = mount-spec
description = "Indicates that the key represents a mount point.

	The value is the filename that should be used for the configuration file
	defined by the specification."
example = default.ecf


[infos]
type= string
status= implemented
usedby/tool= mount-spec
description= "infos about the mount point

	See CONTRACT.ini for individual infos (usedby is tagged with spec).

	hint of application developer that the key actually needs
	a specific plugin (that cannot be derived by other metadata)
	"needs" means that it is semantically absolutely necessary and
	required that such a plugin exists.

	Without the plugin the application might break.
	If the plugin is optional and only nice to have, use recommends
	instead."
note= "It is generally preferred that other metadata will be used to
	deduce the needs of the specification, e.g. use check/validation
	metadata instead of as given above."

[config/needs]
type= string
status= implemented
description= "indicate that the mount point needs some
	configuration for plugins in order to work.

	See CONTRACT.ini for details."





#
# Needed for specification of command line options and environment variables
#
[args]
type= "enum
	remaining
	indexed"
status= implemented
usedby/plugin= gopts
usedby/api= elektraGetOpts kdbopts.h
description= "collect the remaining command line arguments.
	must be set on an array key (basename = '#'), if 'remaining' is used

	must be specified on a key in the 'spec' namespace"

[args/index]
type= long
status= implemented
usedby/plugin= gopts
usedby/api= elektraGetOpts kdbopts.h
description= "the index to use for 'args = indexed'

	must be specified on a key in the 'spec' namespace"

[command]
type= string
status= implemented
usedby/plugin= gopts
usedby/api= elektraGetOpts kdbopts.h
description= "introduces a sub-command

	must be specified on a key in the 'spec' namespace"

[opt]
type= char
status= implemented
usedby/tool= gen
usedby/plugin= gopts
usedby/api= elektraGetOpts kdbopts.h
description= "set a short command line option for this key.
	Per default an option is required, to have an argument.

	short options will be preferred over long options and
	environment variables

	an option can only be specified on a single key

	if the key with this metadata is an array (basename = '#'),
	the option can be repeated an all occurrences will be
	collected into the given array

	must be specified on a key in the 'spec' namespace"

[opt/long]
type= string
status= implemented
usedby/tool= gen
usedby/plugin= gopts
usedby/api= elektraGetOpts kdbopts.h
description= "set a long command line option for this key.
	Per default an option is required, to have an argument.

	short options will be preferred over long options;
	long options will be preferred over environment variables

	an option can only be specified on a single key

	if the key with this metadata is an array (basename = '#'),
	the option can be repeated an all occurrences will be
	collected into the given array

	must be specified on a key in the 'spec' namespace"

[opt/arg]
type= "enum
	required
	optional
	none"
status= implemented
usedby/plugin= gopts
usedby/api= elektraGetOpts kdbopts.h
description= "set the argument mode of this option;
	will be ignored, if neither 'opt' nor 'opt/long' are set

	if set to 'optional' only long options using the '--name=value'
	syntax can be used to specify an argument, all other kinds
	of options behave as if 'none' were set

	if set to 'none' the key will be set to \"1\" or 'opt/flagvalue'

	must be specified on a key in the 'spec' namespace"

[opt/flagvalue]
type= string
status= implemented
usedby/plugin= gopts
useby/api= elektraGetOpts kdbopts.h
description= "set the flag-value of this option
	will be ignored, if neither 'opt' nor 'opt/long' are set

	'opt/arg' must be set to 'none' or 'optional', if the option
	does not have an argument instead of the default \"1\" the
	given value will be used

	must be specified on a key in the 'spec' namespace"

[opt/help]
type= string
status= implemented
usedby/plugin= gopts
usedby/api= elektraGetOpts kdbopts.h
description= "set the help message for this key
	will be ignored, if neither 'opt' nor 'opt/long' are set
	overrides the 'description' metadata

	must be specified on a key in the 'spec' namespace"

[opt/hidden]
type= string
status= implemented
usedby/plugin= gopts
usedby/api= elektraGetOpts kdbopts.h
description= "hides this option from the help message, if set to 1
	will be ignored, if neither 'opt' nor 'opt/long' are set

	must be specified on a key in the 'spec' namespace"

[opt/#]
type= char
status= implemented
usedby/plugin= gopts
usedby/api= elektraGetOpts kdbopts.h
description= "set multiple short command line options for this key.
	only one of these options can be used at the same time

	otherwise the same as 'opt'"

[opt/#/long]
type= string
status= implemented
usedby/tool= gen
usedby/plugin= gopts
usedby/api= elektraGetOpts kdbopts.h
description= "set a long command line option for this key.
	only one of these options can be used at the same time

	otherwise the same as 'opt/long'"

[opt/#/arg]
type= "enum
	required
	optional
	none"
status= implemented
usedby/plugin= gopts
usedby/api= elektraGetOpts kdbopts.h
description= "set the argument mode for option at index #
	will be ignored, if neither 'opt/#' nor 'opt/#/long' are set for
	the same index

	otherwise the same as 'opt/arg'"

[opt/#/flagvalue]
type= string
status= implemented
usedby/plugin= gopts
useby/api= elektraGetOpts kdbopts.h
description= "set the flag-value for option at index #
	will be ignored, if neither 'opt/#' nor 'opt/#/long' are set for
	the same index

	otherwise the same as 'opt/flagvalue'"

[opt/#/hidden]
type= string
status= implemented
usedby/plugin= gopts
usedby/api= elektraGetOpts kdbopts.h
description= "hides option at index # from the help message, if set to 1
	will be ignored, if neither 'opt' nor 'opt/long' are set

	must be specified on a key in the 'spec' namespace"

[env]
type= regex [^=]+
status= implemented
usedby/plugin= gopts
usedby/api= elektraGetOpts kdbopts.h
description= "set an environment variable for this key.
	the value of the given environment variable will be
	assigned to this key.

	short and long options will be preferred over environment
	variables

	environment variables can only be specified on a single key

	if the key with this metadata is an array (basename = '#'),
	the environment variable's value will be split at the character
	';' on Windows and at ':' on any other OS and the result is
	collected into the given array

	must be specified on a key in the 'spec' namespace"

[env/#]
type= regex [^=]+
status= implemented
usedby/plugin= gopts
usedby/api= elektraGetOpts kdbopts.h
description= "set multiple environment variables for this key.
	only one of these variables can be used at the same time.

	otherwise the same as 'env'"

#
# Needed for documentation
#

[see/#]
status= implemented
description = "Pointer to other configuration settings which should also
	be considered to be changed if this configuration setting is changed."
usedby/tool= gen

[rationale]
status= idea
description= "Information why this configuration setting exists
	and in which scenarios it should be considered to be removed"

[requirement]
status= idea
description= "Information based on which requirement the configuration
	setting exists. Gives hints when to reevaluate the configuration
	setting."

[description]
usedby/tool = web
usedby/plugin = getopts
usedby/api = elektraGetOpts kdbopts.h
description = "This is information provided from the developer/maintainer
	for administrators.
	It is not written directly in the configuration files but is instead
	in the spec: namespace.

	elektraGetOpts and the getopts plugin use this information in the help
	message, if 'opt/help' is not provided."
note = For information in other namespaces, use `comment/#` instead.

[example]
usedby/tool = web
description = "It is always good to have an example.

	The example is only for documentation unlike the default
	which will be used if nothing else is given.
	
	Make sure that using all the examples give an overall
	valid configuration."




#
# Information about the key's name
#

[rename/toupper]
type = string
status = implemented
usedby/plugin = rename
description = rename key name to uppercase

[rename/tolower]
type= string
status= implemented
usedby/plugin= rename
description=rename key name to lowercase

[rename/cut]
type= string
status= implemented
usedby/plugin= rename
description=cut out a common name

[rename/to]
type= string
status= implemented
usedby/plugin= rename
description=use a different name instead of the cut out name

[origname]
type= string
status= implemented
usedby/plugin= rename
description= "stores the original name of the key as it was before the
	rename operation"



#
# Spec Plugin
#

[conflict/get/member]
type = "enum
	ERROR
	WARNING
	INFO"
status = implemented
description = sets the conflict handling for member conflicts in kdbGet, see spec plugin README

[conflict/get/invalid]
type = "enum
	ERROR
	WARNING
	INFO"
status = implemented
description = sets the conflict handling for invalid conflicts in kdbGet, see spec plugin README

[conflict/get/count]
type = "enum
	ERROR
	WARNING
	INFO"
status = implemented
description = sets the conflict handling for count conflicts in kdbGet, see spec plugin README

[conflict/get/collision]
type = "enum
	ERROR
	WARNING
	INFO"
status = implemented
description = sets the conflict handling for collision conflicts in kdbGet, see spec plugin README

[conflict/get/missing]
type = "enum
	ERROR
	WARNING
	INFO"
status = implemented
description = sets the conflict handling for missing key conflicts in kdbGet, see spec plugin README

[conflict/get/range]
type = "enum
	ERROR
	WARNING
	INFO"
status = implemented
description = sets the conflict handling for range conflicts in kdbGet, see spec plugin README

[conflict/set/member]
type = "enum
	ERROR
	WARNING
	INFO"
status = implemented
description = sets the conflict handling for member conflicts in kdbSet, see spec plugin README

[conflict/set/invalid]
type = "enum
	ERROR
	WARNING
	INFO"
status = implemented
description = sets the conflict handling for invalid conflicts in kdbSet, see spec plugin README

[conflict/set/count]
type = "enum
	ERROR
	WARNING
	INFO"
status = implemented
description = sets the conflict handling for count conflicts in kdbSet, see spec plugin README

[conflict/set/collision]
type = "enum
	ERROR
	WARNING
	INFO"
status = implemented
description = sets the conflict handling for collision conflicts in kdbSet, see spec plugin README

[conflict/set/missing]
type = "enum
	ERROR
	WARNING
	INFO"
status = implemented
description = sets the conflict handling for missing key conflicts in kdbSet, see spec plugin README

[conflict/set/range]
type = "enum
	ERROR
	WARNING
	INFO"
status = implemented
description = sets the conflict handling for range conflicts in kdbSet, see spec plugin README

[array/min]
type = array-index
status = implemented
description = Sets the minimum element of an array. See also spec plugin README.
example = #1

[array/max]
type = array-index
status = implemented
description = Sets the maximum element of an array. See also spec plugin README.
example = #_10

[require]
type = empty
status = implemented
usedby/pluign = spec
description = "Requires the key to be present. See also spec plugin README.
	
	Cannot be used together with `default`.
	
	If possible, prefer `default`, as it is more user-friendly."
note = "Used to be called `required`.
	Not to be confused to `required` for `opt/arg`."



#
# Error and Warnings
#

[error]
status = implemented
description = an error, see doc/dev/error-handling.md

[warnings/#]
status = implemented
description = a number of warnings, see doc/dev/error-handling.md






#
# Validation/Checks about the key's value
#

[check/type]
type= "enum
	short
	unsigned_short
	long
	unsigned_long
	long_long
	unsigned_long_long
	float
	double
	long_double
	char
	boolean
	octet
	any
	empty
	FSType
	string"
status= implemented
usedby/plugin= range type
usedby/tool = web
description= "defines the type of the value, as specified in CORBA
	(except of 2: wchar, wstring; and 4 additions: any, empty, FSType, string).
	enum is implemented by check/enum/#
	FSType is deprecated

	Unlike type, check/type is *only* used for validation.

	Tools with support for `check/type`, should also always check for `type`.
	The type plugin prefers `check/type` if it is present.
			 
	 The range plugin uses type as fallback, if check/type is not specified."
example = any

[check/range]
status= implemented
usedby/plugin= range
usedby/tool = web
description= range checks, from-to, multiple ranges are separated by a comma
example= -1-4,6-10

[check/math]
type= string
status = implemented
usedby/plugin= mathcheck
description= check if value conforms to mathematical expression

[check/email]
type= string
status = implemented
usedby/plugin= email
description= check if the given email address is valid based on regular expression

[check/ipaddr]
type= "enum
	
	ipv4
	ipv6"
status = implemented
usedby/plugin= network ipaddr
description= "check if value resolves correctly to an ipaddr
	empty value uses either ipv4 or ipv6"

[check/port]
type= string
status = implemented
usedby/plugin= network
description= "check if the given port is either a service under /etc/services or
	is between 0 - 65535 (both inclusive)"

[check/port/listen]
type= string
status = implemented
usedby/plugin= network
description= "check if the given port is either a service under /etc/services or
	is between 0 - 65535 (both inclusive) and is unused so that potential
	applications can start with that port"

[check/format]
type= string
status= idea
description= defines the format of the value

[check/path]
status= implemented
usedby/plugin= path
description= defines which file (path) the value refers to

[check/validation]
status= implemented
usedby/plugin= validation
usedby/tool = web
type= regular expression
description= a regular expression to check against

[check/validation/message]
status= implemented
usedby/plugin= validation
usedby/tool = web
description= the message added to the error if validation fails

[check/validation/match]
status= implemented
usedby/plugin= validation
description= if it should be matched against LINE or WORD

[check/validation/ignorecase]
status= implemented
usedby/plugin= validation
description= to ignore case when matching

[check/validation/invert]
status= implemented
usedby/plugin= validation
description= to invert match

[check/validation/type]
type="enum
	ERE
	BRE"
status= deprecated
usedby/plugin= validation
description= type of match, to toggle REG_EXTENDED

[check/enum]
status=deprecated
usedby/plugin= enum type
description= List of apostrophe enclosed values separated by
	commas to check against.
	Please use check/enum/# instead.

[check/enum/#]
status= implemented
usedby/plugin= enum type
usedby/tool = web
description= "An array with different enum values to be used
	instead of check/enum"

[check/enum/multi]
status= implemented
usedby/plugin= enum
type= char
description= "Specifies if multiple, but different, strings are allowed
	within a value. The character given within this metavalue
	is the separator."
example= _

[check/enum/delimiter]
status= implemented
usedby/plugin= type
type= char
description= "Specifies if multiple, but different, strings are allowed
	within a value. The character given within this metavalue
	is the separator."
example= _

[check/path/mode]
status= implemented
usedby/plugin= path
type= "enum
	r
	w
	x
	rw
	rx
	wx
	rwx"
description= "A check to see if a certain user has correct permissions on a file. Permissions are
	either r (read) w (write) x (execute) and any combination of them. Whereas check/path only
	checks for the existence of a given path, check/path/mode also tests for the right permissions.
	If check/path is not given, check/path/mode will be ignored.
	The respective user which must have these permissions is declared in check/path/user.
	If no user is given in check/path/user (simply an empty string), the current user is taken to check for
	permissions. The plugin only checks if `r`, `w` or `x` is present and ignores all other characters."
example = rwx

[check/path/user]
status= implemented
usedby/plugin= path
type= "string
	empty"
description= "Used by check/path to see if the given user has the correct permissions. If empty
	it takes the current user."

[check/calculate]
status= implemented
usedby/plugin= calculate
type= string
description= "A string starting with a logical comparator symbol
	followed by a Polish prefix notation to calculate a value
	to check against."

[check/condition]
status= implemented
usedby/plugin= conditionals
type= string
description= "A ternary conditional style operator to define
	relations between keys"

[check/condition/any/#]
status= implemented
usedby/plugin= conditionals
type= string
description= An array of multiple condition statements

[check/condition/all/#]
status= implemented
usedby/plugin= conditionals
type= string
description= An array of multiple condition statements

[check/condition/none/#]
status= implemented
usedby/plugin= conditionals
type= string
description= An array of multiple condition statements

[condition/validsuffix]
status= implemented
usedby/plugin= conditionals
type= string
description= A unit of measure style prefix

[assign/condition]
status= implemented
usedby/plugin= conditionals
type= string
description= "A ternary conditional style operator to assign
	a value depending on a condition"

[assign/condition/#]
status= implemented
usedby/plugin = conditionals
type= string
descriptions= Array of assign/condition metadata

[check/date]
status= implemented
usedby/plugin= date
type= enum
	POSIX
	ISO8601
	RFC2822
description= Support of some standards for a date specification.

[check/date/format]
status= implemented
usedby/plugin= date
type= string
description= "A format for a date specification.
	(If required by standard selected by check/date.)"

[check/reference]
status= implemented
usedby/plugin= reference
type= "enum
	single
	recursive
	alternative"
description= Marks this key as referencing another key

[check/reference/restrict]
status= implemented
usedby/plugin= reference
type= string
description= Globbing pattern used to restrict valid references

[check/reference/restrict/#]
status= implemented
usedby/plugin= reference
type= string
description= Same as `check/reference/restrict` but in array notation for multiple restrictions

[trigger/warnings]
usedby/plugin= error
type= long
status= implemented
description= Trigger a warning with given warning number from src/error/specifications

[trigger/error]
usedby/plugin= error
type= long
status= implemented
description= Trigger an error with given error number from src/error/specifications

[trigger/error/nofail]
usedby/plugin= error
type= long
status= implemented
description= Add the error but do not fail (to test robustness of framework).

[check/macaddr]
status= implemented
type= empty
usedby/plugins= macaddr
description = "Marks a key as MAC address. Used to validate MAC addresses and
	returns integer representations on get."

[check/rgbcolor]
type= empty
status = implemented
usedby/plugin= rgbcolor
description= "check if value is a valid rgbcolor in hexformat
	will normalize all values to decimal rrggbbaa"

[check/unit]
type= empty
status = implemented
usedby/plugin= unit
description= "check if unit is a valid unit of memory
	will normalize units of memory into byte, unit of memory e.g. 400MB or 500 GB, 200 M B is not valid"

[check/blacklist/#]
status= implemented
usedby/plugin= blacklist
description= "An array with different blacklisted values"

[check/length/max]
status= implemented
usedby/plugin= length
description= "checks if length is less or equal to given value"


#
# Other information about keys
#

[deprecated]
status= idea
description= Flag keys that will be removed in further versions
note= thanks to Config::Model for that idea

[source]
status= idea
description= "states where a key comes from if it is not from an ordinary
	persistent configuration. E.g. hardware (queries)
	e.g. system:/sw/xorg/current/monitor might have "source" metadata if it
	is queried from hardware and not from configuration file."

[fixed]
status= idea
description= The key will return the given value in any case.

[restrict/write]
status= idea
usedby/tool = web
description= avoid writing on the value of the key, it still can be removed

[restrict/binary]
status= idea
usedby/tool = web
description= binary keys are not allowed

[restrict/remove]
status= idea
usedby/tool = web
description= avoid removal of key (needs schema-checker to read key)

[evaluate/<language>]
type= program code
status= idea
description= "Evaluate expression to check if key should be included, program should
	abort or however evaluate plugin is configured"

[accessibility]
status= idea
description= who is allowed to edit this configuration setting?

[visibility]
status = implemented
usedby/tool = web
type = "enum
	critical
	important
	user
	advanced
	developer
	internal"
description = "Who should see this configuration setting?
	This is the equivalent of priority in debconf.
	If no visibility is given, "user" is assumed.

	The meaning is:
	- critical: setting must be changed, otherwise the system/application will fail. (e.g. boot device, hostname)
	- important: setting has no reasonable default and most likely will fail, should be set so that application is (more) useful. (e.g. website URL to serve, relay host for mail relay)
	- user: often has reasonable default but most users would like to see it
	- advanced: settings most users do not want to see (e.g. related to resource usage) or to enable experimental features or where defaults usually work
	- developer: settings only relevant for developers of the application
	- internal: settings which should not be seen by anyone. (e.g. intermediate steps for calculations)"





#
# Reserved names, not to be used by metadata
#

[spec]
description= to not avoid metakeys with standard spec keys, no metakey name must begin with spec

[proc]
description= to not avoid metakeys with standard proc keys, no metakey name must begin with proc

[dir]
description= to not avoid metakeys with standard dir keys, no metakey name must begin with dir

[user]
description= to not avoid metakeys with standard user keys, no metakey name must begin with user

[system]
description= to not avoid metakeys with standard system keys, no metakey name must begin with system

[string]
description= "needed for formatting strings in error messages: %string% should refer to the
	string of the key, not to metadata \"string\""

[value]
description= "needed for formatting values in error messages: %value% should refer to the
	value of the key, not to metadata \"value\""




#
# Plugin specific Metadata
#

[crypto/encrypt]
status= implemented
usedby/plugins= crypto
type= string
description= used to mark a key for encryption. The crypto plugin is supposed to encrypt the key. After the encryption the type of the key will be set to "binary". Its original type will be restored after decryption.

[crypto/salt]
status= implemented
usedby/plugins= crypto
type= string
description= "used to store the salt that seeds the Key Derivation Function, which is used for deriving the cryptographic key and the initialization vector (IV).
	The salt is re-generated on every encryption call (called by kdb set) so no key and IV combination is ever used twice.
	No special protection is required for the salt. It can be persisted as plain text."

[gpg/binary]
status= implemented
usedby/plugins= gpgme
type= string
description= used to mark a key that contained a binary value before encryption.

[xerces/rootname]
status= implemented
usedby/plugins= xerces
type= string
description= "Used to store the name of the xml file's original root element when mounting to a mount point which name doesn't correspond to the xml root element.
	This metadata will be stored in the mount point key. When writing or exporting again, the stored name will be used for the root element of the corresponding xml document."

[unit/base]
type = dec hex
default = dec
usedby/plugins = hexnumber
description = "used to specify the base of an integer value. Currently only the hexnumber plugin supports this metadata. It converts any value marked as "hex" from
	hexadecimal into decimal when the configuration is read, and back when it is written. The hexnumber plugin also ensures that a value marked as \"hex\" starts with \"0x\" or \"0X\"."

[origvalue]
status = implemented
type = string
usedby/plugins = type boolean
description = "Used by plugins that normalize and restore key values for storing the original key value. Plugins should ALWAYS use this metakey. This key will be cleared on keySetString,
	so if it is present, the key is unchanged and should be restored. Plugins should NEVER overwrite or remove this metakey, if it is present, because this may break other plugins. If a
	plugins needs to normalize a value, but 'origvalue' is already set, an error should be produced, because to plugins cannot be responsible for normalizing the same keys."

[check/boolean/true]
status = implemented
type = string
usedby/plugins = type
description = "Overrides the allowed true value for this key. Only the given value or 1 will be allowed as true. All true keys will be restored to this value in `kdbSet`.
	Must be used together with check/boolean/false."

[check/boolean/false]
status = implemented
type = string
usedby/plugins = type
description = "Overrides the allowed false value for this key. Only the given value or 0 will be allowed as false. All false keys will be restored to this value in `kdbSet`.
	Must be used together with check/boolean/true."

[cache/clear]
status = implemented
usedby/plugins = cache
type = boolean
description = Tells the cache plugin to remove all cache files during the next `kdbGet` in a safe way.

[tomltype]
status = implemented
usedby/plugins = toml
type = "enum
	simpletable
	tablearray
	inlinetable"
descriptions = "Tells the TOML plugin, which kind of TOML structure a key represents. When reading a TOML file, the plugin sets this metakey when encountering a TOML structure.
	On writing, it is used for writing the structure back into a TOML file.
	No metakey inference is done on writing, it's either set by a previous read of a TOML file or set explicitly by the user."