# API Attributes

Neutron’s resource attributes are defined in dictionaries in `api/definitions`.

The map containing all installed resources (for core and active extensions) is in `api/attributes.py`.

## Attribute map structure

Example attribute definitions for `dns_name`:

    'dns_name': {
        'allow_post': True,
        'allow_put': True,
        'default': '',
        'convert_to': convert_to_lowercase,
        'validate': {'type:dns_name': FQDN_MAX_LEN},
        'is_visible': True
    },

The `validate` item specifies rules for validating the attribute.

The `convert_to` item specifies rules for converting the attribute.

Example attribute definitions for `gateway_ip`:

    'gateway_ip': {
        'allow_post': True,
        'allow_put': True,
        'default': constants.ATTR_NOT_SPECIFIED,
        'validate': {'type:ip_address_or_none': None},
        'is_visible': True
    }

Note: a default of `ATTR_NOT_SPECIFIED` indicates that an attribute is not required, but will be generated by the plugin if it is not specified. Particularly, a value of `ATTR_NOT_SPECIFIED` is different from an attribute that has been specified with a value of `None`. For example, if `gateway_ip` is omitted in a request to create a subnet, the plugin will receive `ATTR_NOT_SPECIFIED` and the default gateway IP will be generated. However, if `gateway_ip` is specified as `None`, this means that the subnet does not have a gateway IP.

The following are the defined keys for attribute maps:

`default` | default value of the attribute (if missing, the attribute becomes mandatory)
`allow_post` | the attribute can be used on `POST` requests
`allow_put` | the attribute can be used on `PUT` requests
`validate` | specifies rules for validating data in the attribute
`convert_to` | transformation to apply to the value before it is returned
`convert_list_to` | if the value is a list, apply this transformation to the value before it is returned
`is_filter` | the attribute can be used in `GET` requests as filter
`is_sort_key` | the attribute can be used in `GET` requests as sort_key
`is_visible` | the attribute is returned in `GET` responses
`required_by_policy` | the attribute is required by the policy engine and should therefore be filled by the API layer even if not present in request body
`enforce_policy` | the attribute is actively part of the policy enforcing mechanism, ie: there might be rules which refer to this attribute
`primary_key` | Mark the attribute as a unique key.
`default_overrides_none` | if set, if the value passed is None, it will be replaced by the `default` value
`dict_populate_defaults` | if set, the `default` values of keys inside dict attributes, will be filled if not specified

When extending existing sub-resources, the sub-attribute map must define all extension attributes under the `parameters` object. This instructs the API internals to add the attributes to the existing sub-resource rather than overwrite its existing definition. For example:

    SUB_RESOURCE_ATTRIBUTE_MAP: SubResourceAttributeMap = {
        'existing_subresource_to_extend': {
            'parameters': {
                'new_attr1': {
                    'allow_post': False,
                    # etc..
                }
            }
        }
    }

this page last updated: 2026-08-15 12:38:23

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug