Get work package schema
get_work_package_schemaGet the required fields, writable attributes, and custom field options for a work package type in a project, enabling correct creation or update of work packages.
Instructions
Show which fields a work package of this type accepts in this project.
Call it before create_work_package/update_work_package when you need the
required fields, when you want a custom field's key or its allowed options, or after
a 422 that named a field you do not recognise.
Returns required_fields (writable keys you must supply), fields — every core
attribute with {key, name, type, required, writable, has_default, allowed_values}
— and custom_fields with {key, name, type, required, writable, options}.
allowed_values/options are {id, name} lists for status, category, version
and list/user custom fields.
Pitfalls: key is the wire spelling (startDate, customField12) — that is
what raw_filters and custom_fields writes use, though writes also accept the
display name. A field with writable: false is computed by OpenProject; sending it
is an error, not a no-op. allowed_values is null when the API only offers a lookup
URL (assignee, project) — resolve those with search_principals or list_projects
instead. Long option lists are capped at 50 with a marker in notes.
Ids for both parameters come from get_project_metadata; to read the values
actually set on one work package use get_work_package.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| refresh | No | Bypass the cache after an administrator changed the type or its custom fields. | |
| type_id | Yes | Numeric work-package type id from get_project_metadata(project_id=...).types — not the type name. | |
| project_id | Yes | Numeric project id — this endpoint does not accept the string identifier. The schema is per project AND type: the same type carries different custom fields in another project. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | Degradation notes, e.g. capped allowed-value lists. | |
| fields | No | Core attributes with type/required/writable. | |
| type_id | Yes | Work-package type the schema was requested for. | |
| project_id | Yes | Project the schema was requested for. | |
| custom_fields | No | Always a list; empty when the type has none. | |
| required_fields | No | Writable keys that must be supplied on create. |