Skip to content

OpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub

Update Project schema api docs to include _attributeGroups

Dombi Attila773ad70f80f5
diff --git a/docs/api/apiv3/components/schemas/projects_schema_model.yml b/docs/api/apiv3/components/schemas/projects_schema_model.yml
index 179be856cdd..f920c6e9ea4 100644
--- a/docs/api/apiv3/components/schemas/projects_schema_model.yml
+++ b/docs/api/apiv3/components/schemas/projects_schema_model.yml
@@ -1,9 +1,111 @@
# Schema: Projects_schemaModel
---
type: object
+description: |-
+ A schema for a project. This schema defines the attributes of a project.
+
+properties:
+ _type:
+ type: string
+ enum: [Schema]
+ description: The type identifier for this resource
+ _dependencies:
+ type: array
+ description: Schema dependencies (currently empty for projects)
+ _attributeGroups:
+ type: array
+ items:
+ type: object
+ properties:
+ _type:
+ type: string
+ enum: [ProjectFormCustomFieldSection]
+ description: The type identifier for this resource
+ name:
+ type: string
+ description: The human-readable name of the custom field section
+ attributes:
+ type: array
+ items:
+ type: string
+ description: |-
+ Array of camelCase custom field attribute names belonging to this section.
+ Only includes custom fields visible to the current user.
+ description: |-
+ Defines the organizational structure of project custom fields into sections for UI rendering.
+
+ Each attribute group represents a project attribute section containing related project attributes.
+ The sections determine how project attributes are visually organized and grouped in forms.
+
+ **Key behaviors:**
+ - Admin-only project attributes appear only for users with admin privileges
+ - Empty sections (with no accessible project attributes) are omitted from the response
+ - The order reflects the configured section positioning in admin settings
+ - Each section contains only project attributes assigned to that specific section
+
+ **Example structure:**
+ ```json
+ [
+ {
+ "_type": "ProjectFormCustomFieldSection",
+ "name": "Project Details",
+ "attributes": ["customField1", "customField3"]
+ },
+ {
+ "_type": "ProjectFormCustomFieldSection",
+ "name": "Budget Information",
+ "attributes": ["customField2", "customField4"]
+ }
+ ]
+ ```
+ id:
+ $ref: './schema_property_model.yml'
+ name:
+ $ref: './schema_property_model.yml'
+ identifier:
+ $ref: './schema_property_model.yml'
+ description:
+ $ref: './schema_property_model.yml'
+ public:
+ $ref: './schema_property_model.yml'
+ active:
+ $ref: './schema_property_model.yml'
+ status:
+ $ref: './schema_property_model.yml'
+ statusExplanation:
+ $ref: './schema_property_model.yml'
+ parent:
+ $ref: './schema_property_model.yml'
+ createdAt:
+ $ref: './schema_property_model.yml'
+ updatedAt:
+ $ref: './schema_property_model.yml'
+ _links:
+ type: object
+ description: Links related to this resource
+ properties:
+ self:
+ type: object
+ properties:
+ href:
+ type: string
+ example: "/api/v3/projects/schema"
+
example:
_type: Schema
_dependencies: []
+ _attributeGroups:
+ - _type: ProjectFormCustomFieldSection
+ name: Project Details
+ attributes:
+ customField30
+ customField34
+ - _type: ProjectFormCustomFieldSection
+ name: Budget Information
+ attributes:
+ customField31
+ customField32
+ customField35
id:
type: Integer
name: ID
diff --git a/docs/api/apiv3/paths/projects_schema.yml b/docs/api/apiv3/paths/projects_schema.yml
index f15190f751c..8b033c89663 100644
--- a/docs/api/apiv3/paths/projects_schema.yml
+++ b/docs/api/apiv3/paths/projects_schema.yml
@@ -9,6 +9,18 @@ get:
response:
value:
_dependencies: []
+ _attributeGroups:
+ - _type: ProjectFormCustomFieldSection
+ name: Project Details
+ attributes:
+ - customField30
+ - customField34
+ - _type: ProjectFormCustomFieldSection
+ name: Budget Information
+ attributes:
+ - customField31
+ - customField32
+ - customField35
_links:
self:
href: "/api/v3/projects/schema"
diff --git a/docs/development/concepts/resource-schemas/README.md b/docs/development/concepts/resource-schemas/README.md
index 1064689db7d..fb3fe11f487 100644
--- a/docs/development/concepts/resource-schemas/README.md
+++ b/docs/development/concepts/resource-schemas/README.md
@@ -74,6 +74,9 @@ An exemplary schema response on the Community for the OpenProject project (`ID=1
The work package schema also contains the reference to the attribute groups from the form configuration in the `_attributeGroups` property.
+The project schema also contains the reference the project attribute sections and their project attributes in the `_attributeGroups` property.
+
+
## Frontend usage
The OpenProject frontend usually ensure that whenever you get access to a HAL resource, its associated schema (if there is any) is also loaded. This is done through the [`SchemaCacheService`](https://github.com/opf/openproject/blob/dev/frontend/src/app/core/schemas/schema-cache.service.ts). It will request the associated schema unless it has already been cached in the global states object to avoid loading a schema multiple times.