writeOnly : Boolean

writeOnly

Boolean

This keyword indicates that the value is never present when the instance is retrieved from the owning authority.

Value	This keyword must be set to a boolean value Hint: Use the `jsonschema metaschema` and `jsonschema lint` commands to catch keywords set to invalid values
Kind	Annotation
Applies To	Any
Base Dialect	2020-12
Changed In	None
Introduced In	Draft 7
Vocabulary	Meta Data
Specification	https://json-schema.org/draft/2020-12/json-schema-validation.html#section-9.4
Metaschema	https://json-schema.org/draft/2020-12/meta/meta-data
Official Tests	None
Default	`false`
Annotation	Boolean The boolean value set by this keyword Hint: Use the `jsonschema validate` command to collect annotations from the command-line
Affected By	None
Affects	None
Also See	readOnly (Vocabulary: Meta-Data) title (Vocabulary: Meta-Data) description (Vocabulary: Meta-Data) examples (Vocabulary: Meta-Data) default (Vocabulary: Meta-Data) deprecated (Vocabulary: Meta-Data)

The writeOnly keyword, when set to true, signifies that an instance value (such as a specific object property) can be modified or removed but not read, whatever that means in the context of the system. For example, form generators may rely on this keyword to mark the corresponding input as as a password field. This keyword does not affect validation, but the evaluator will collect its value as an annotation.

Best Practice

Avoid setting this keyword to the default value false. If an instance value is not considered to be write only, the best practice is to omit the use of this keyword altogether. This prevents unnecessarily generating and collecting an annotation that does not carry any additional meaning.

Also avoid simultaneously setting this keyword and the readOnly keyword to true for the same instance location, resulting in ambiguous semantics.

Common Pitfall

Tooling makers must be careful when statically traversing schemas in search of occurences of this keyword. It is possible for schemas to make use of this keyword behind conditional operators, references, or any other type of keyword that makes it hard or even impossible to correctly locate these values without fully evaluating the schema against an instance. The only bullet proof method is through annotation collection.

For example, an instance property might only be write only under certain conditions determined by a dynamic operator like anyOf.

Examples

A schema that statically marks the password optional object property as write only Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "username": { "type": "string" }
    "password": { "type": "string", "writeOnly": true },
  }
}

Valid An object value that defines the write only property is valid but an annotation is emitted Instance

{ "username": "jviotti", "password": "mysupersecretpassword" }

Annotations

{ "keyword": "/properties/password/writeOnly", "instance": "/password", "value": true }

Valid An object value that does not define the write only property is valid and no annotation is emitted Instance

{ "username": "jviotti" }

Invalid An object value that does not match the schema is invalid and no annotations are emitted Instance

{ "password": null }

A schema that dynamically marks the password optional object property as write only based on the presence of the username property Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "username": { "type": "string" }
    "password": { "type": "string" },
  }
  "dependentSchemas": {
    "username": {
      "properties": { "password": { "writeOnly": true } }
    }
  }
}

Valid An object value that defines both properties is valid but an annotation is emitted Instance

{ "username": "jviotti", "password": "mysupersecretpassword" }

Annotations

{ "keyword": "/dependentSchemas/username/properties/password/writeOnly", "instance": "/password", "value": true }

Valid An object value that only defines the username property is valid and no annotation is emitted Instance

{ "username": "jviotti" }

Valid An object value that only defines the password property is valid and no annotation is emitted Instance

{ "password": "mysupersecretpassword" }