feat(jsonschema): add support for normalization/denormalization with attributes

[Maxcastel]

Q	A
Branch?	4.2
Tickets	Closes #7536
License	MIT

ApiResource examples:

#[ApiResource(
    operations: [
        new Get(
            normalizationContext: [
                'attributes' => ['title', 'name', 'author' => ['name']],
            ],
        ),
        new Post(
            denormalizationContext: [
                'attributes' => ['title', 'name', 'author' => ['name']], 
            ],
            normalizationContext: [
                'attributes' => ['id', 'title', 'author' => ['id', 'name']],
            ],
        )
    ]
)]
class Book
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column(type: 'integer')]
    private ?int $id = null;

    #[Groups(['book:read'])]
    #[ORM\Column(type: 'string', length: 255)]
    public string $title = 'The book title';

    #[ORM\Column(type: 'string', length: 255)]
    private ?string $name = null;

    #[ORM\ManyToOne(targetEntity: Author::class)]
    #[ORM\JoinColumn(nullable: false)]
    private Author $author;
    
    #[ORM\Column(type: 'string', length: 20)]
    public string $isbn = '978-3-16-148410-0';

    // getters and setters
}

#[ApiResource]
class Author
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column(type: 'integer')]
    private ?int $id = null;

    #[Groups(['user:read', 'user:write'])]
    #[ORM\Column(type: 'string', length: 255)]
    private string $name;

    // getters and setters
}

Before

API response

/api/books/id GET:

API Docs

JSON Schema

bin/console api:openapi:export --output=swagger_docs.json

"application/json": {
    "schema": {
        "$ref": "#/components/schemas/Book"
    }
}

"Book": {
    "type": "object",
    "properties": {
        "id": {
            "readOnly": true,
            "type": "integer"
        },
        "title": {
            "default": "The book title",
            "type": "string"
        },
        "name": {
            "type": "string"
        },
        "author": {
            "type": "string",
            "format": "iri-reference",
            "example": "https://example.com/"
        },
        "isbn": {
            "default": "978-3-16-148410-0",
            "type": "string"
        }
    }
}

Now

API response

/api/books/id GET:

API Docs

JSON Schema

"application/json": {
    "schema": {
        "$ref": "#/components/schemas/Book-title_name_author.name"
    }
}

"Book-title_name_author.name": {
    "type": "object",
    "properties": {
        "title": {
            "default": "The book title",
            "type": "string"
        },
        "name": {
            "type": "string"
        },
        "author": {
            "$ref": "#/components/schemas/Author-name"
        }
    }
}

"Author-name": {
    "type": "object",
    "properties": {
        "name": {
            "type": "string"
        }
    }
}

[soyuka]

This looks nice, can you add a test on the JsonSchema generation (tests/Functional/JsonSchema/JsonSchemaTest.php) as I'm not sure that we'd gather the correct properties.

[Maxcastel]

I rebased onto 4.2 to retrieve the code that fixes the 8 failing tests.

[Maxcastel]

This looks nice, can you add a test on the JsonSchema generation (tests/Functional/JsonSchema/JsonSchemaTest.php) as I'm not sure that we'd gather the correct properties.

Done in c2b0997 @soyuka

[Copilot]

Pull request overview

This PR adds support for using the attributes context option in normalization and denormalization, similar to how serialization groups currently work. This allows developers to control which properties are exposed in API responses and accepted in requests through the attributes context, providing an alternative to serialization groups for controlling API visibility.

Changes:

• Added support for attribute-based property filtering in normalization/denormalization contexts
• Updated schema generation to reflect attribute-based filtering in OpenAPI documentation
• Added comprehensive test coverage for the new attribute filtering functionality

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/Metadata/Property/Factory/SerializerPropertyMetadataFactory.php	Added logic to extract and apply normalization/denormalization attributes when determining property read/write/link permissions
src/JsonSchema/SchemaFactory.php	Updated schema building to propagate attribute context to child properties and extract attributes from operation contexts
src/JsonSchema/DefinitionNameFactory.php	Extended definition name generation to include attributes in the naming scheme alongside groups
tests/Functional/JsonSchema/JsonSchemaTest.php	Added functional test verifying schema generation with attribute-based filtering
tests/Fixtures/TestBundle/ApiResource/ParentAttribute.php	New fixture class demonstrating parent resource with attribute-based filtering
tests/Fixtures/TestBundle/ApiResource/ChildAttribute.php	New fixture class demonstrating child resource in attribute filtering scenarios
src/Metadata/Tests/Property/Factory/SerializerPropertyMetadataFactoryTest.php	Added unit tests for attribute-based property filtering logic
src/JsonSchema/Tests/SchemaFactoryTest.php	Added unit tests for schema generation with serializer attributes
src/JsonSchema/Tests/Fixtures/ApiResource/ParentAttributeDummy.php	New test fixture for schema factory attribute testing
src/JsonSchema/Tests/Fixtures/ApiResource/ChildAttributeDummy.php	New test fixture for child resource in schema factory tests
src/JsonSchema/Tests/DefinitionNameFactoryTest.php	Added test cases for definition name generation with attributes

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

When a string key exists with a string value (non-array), the logic concatenates key and value with an underscore. However, this appears to be treating the value as a property name, but it should likely just use the key. For example, if the input is ['author' => 'someValue'], this produces 'author_someValue' instead of just 'author'. This doesn't match the pattern used for array values (line 125) where only the key is used as a prefix.

Suggested change

	$parts[] = $key.'_'.$value;
	$parts[] = $key;

[Maxcastel]

done in 8bc6e8d (see: #7629 (comment))

[Maxcastel]

I removed .'_'.$value as suggested here in 8bc6e8d.

Since ['author' => 'name'] is not a valid format (according to the documentation), it ends up including all properties of author.

Example

For ['author' => 'name'] (invalid format):

'attributes' => ['title', 'name', 'author' => 'name']

JSON result and api doc :

{
  "title": "The book title",
  "name": "string",
  "author": {
    "id": 3,
    "name": "string"
  }
}

Before ($parts[] = $key.'_'.$value;)

"schema": {
  "$ref": "#/components/schemas/Book-title_name_author_name"
}

"Book-title_name_author_name": {
  "type": "object",
  "properties": {
    "title": {
      "default": "The book title",
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "author": {
      "$ref": "#/components/schemas/Author"
    }
  }
}

"Author": {
  "type": "object",
  "properties": {
    "id": {
      "readOnly": true,
      "type": "integer"
    },
    "name": {
      "type": "string"
    }
  }
}

After ($parts[] = $key;)

"schema": {
  "$ref": "#/components/schemas/Book-title_name_author"
}

"Book-title_name_author": {
  "type": "object",
  "properties": {
    "title": {
      "default": "The book title",
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "author": {
      "$ref": "#/components/schemas/Author"
    }
  }
}

"Author": {
  "type": "object",
  "properties": {
    "id": {
      "readOnly": true,
      "type": "integer"
    },
    "name": {
      "type": "string"
    }
  }
}

It seems more consistent to keep only author in the schema name when the format is invalid, since in that case all properties of author are included anyway.

[soyuka]

Awesome !

[soyuka]

One last thing I consider this a new feature, could you target main ? you can also squash your commits to a single one feat(jsonschema): ...

[Maxcastel]

Done @soyuka

After targeting main, PHP CS Fixer fails.