Editing a schema component

Schemas provide developers with information about the request they should make, or the response they should expect to receive, when calling an API operation. You can edit schemas that have been previously created in various places in your API definition.

You can configure the following schema settings:

• Schema Name: Available if you are editing a schema component, this name defines a key that enables this schema to be referenced from elsewhere in the API definition; the reference has the following format:

  #/components/schemas/Name

  To change the name, click the Source icon, change the value in the field, then click Save
• Optional: Title: The schema title.
• Optional: Type: The schema data type; select one of the following:
  • • array
    • boolean
    • integer
    • number
    • object
    • string

  Note: If you change the type of an existing schema, any existing settings that are not relevant to the new type are still retained in the OpenAPI source even though they are no longer displayed in the user interface. You should therefore avoid porting a schema from one type to another but instead either create a new schema or modify the OpenAPI source directly; to open the source editor, click the Source icon .
• Properties: The schema property. To add a property to the schema, click Add alongside the Properties section heading, complete the details and click Save.
• Additional schema settings dependent on the selected Type of property. To view and edit these schema settings, click the Options menu next to the property you want to view and select Details.
  • boolean: no type specific settings.
  • integer:
    • Format: An optional data type modifier. For more information, see Data Types in the OpenAPI Specification.
    • Multiple Of: Division of an integer instance by this value must result in an integer.
    • Maximum: An integer instance must be less than or equal to this value.
    • Exclusive Maximum: An integer instance must be strictly less than this value.
    • Minimum: An integer instance must be greater than or equal to this value.
    • Exclusive Minimum: An integer instance must be strictly greater than this value.
  • number:
    • Format: An optional data type modifier. For more information, see Data Types in the OpenAPI Specification.
    • Multiple Of: Division of a number instance by this value must result in an integer.
    • Maximum: A number instance must be less than or equal to this value.
    • Exclusive Maximum: A number instance must be strictly less than this value.
    • Minimum: A number instance must be greater than or equal to this value.
    • Exclusive Minimum: A number instance must be strictly greater than this value.
  • object:
    • Max Properties: The number of properties in an object instance must be less than or equal to this value.
    • Min Properties: The number of properties in an object instance must be greater than or equal to this value.
    • Required Properties: An array of property names; every property name in the array must be the name of a property in an object instance. To add a required property name, click Add alongside the Required Properties section heading, enter the name, then click Create.
  • string:
    • Format: An optional data type modifier. For more information, see Data Types in the OpenAPI Specification.
    • Pattern: A regular expression; a string instance must successfully match the expression.
    • Max Length: The maximum allowed number of characters in a string instance.
    • Min Length: The minimum allowed number of characters in a string instance.
    • Enum: An array of string values; a string instance must match one of the array values. To add an enum value, click Add, enter the value, then click Create.
• General settings; select the required options:
  • Required: A property associated with this schema is required.
  • Read Only: A property associated with this schema can be returned in a response but should not be included in a request. For example, properties whose values are system generated identifiers will be defined as Read Only because application clients wouldn't be able to set these.
• Example Value: An example value. Whatever you enter here is displayed as-is in the Developer Portal.
• External Documentation: An external resource for extended documentation; provide the following information:
  • URL (required): The URL for the target documentation.
  • Description: An optional description of the target documentation. You can use CommonMark syntax for rich text representation.
• Xml: Metadata that allows for more fine-tuned XML model definitions; provide the following information:
  • Name: Replaces the name of the element or attribute used for the described schema property.
  • Namespace: The URL of the namespace definition.
  • Prefix: The prefix to be used for the Name.
  • Attribute: Specifies whether the property definition translates to an attribute instead of an element.
  • Wrapped: For an array definition, Specifies whether the array is wrapped (for example, <books><book/><book/></books>) or unwrapped (<book/><book/>).
• Click Save when done.