Standardizing "portrait" attribute and complex binary claims in Authentic Source API

[gianpaolo-tndigit]

Description

Following the discussion in italia/eid-wallet-it-regioni#20 regarding the inclusion of employee photographs via Base64, I would like to clarify the best practice for extending the current API schema to support the portrait attribute and other domain-specific claims (e.g., professional qualifications, blood type).

Technical Considerations

The current CredentialClaimsResponse schema defines attributeClaims using additionalProperties restricted to the string type.

1. userClaims Extensibility: Can userClaims be extended to include a portrait? Since a photograph is a core identity attribute, it might logically reside here, but the current schema lists specific fields like given_name and family_name.
2. attributeClaims String Constraint: Because the schema strictly requires string values for additional properties, complex metadata cannot be sent as objects or arrays. To include a portrait with its associated metadata (encoding, content-type, ISO 19794-5 quality compliance) , we must adapt the data to fit this constraint.

Proposed Approach: Flattened Structure (Schema Compliant)

To satisfy the string requirement in attributeClaims while providing all necessary metadata for ISO/IEC 19794-5 compliance , I propose using a flat key-value mapping where every value is a string:

{
  "portrait_type": "string",
  "portrait_format": "binary",
  "portrait_description": "Person's photograph as binary string (JPEG or JPEG2000). The portrait image SHALL comply with the quality requirements for a Full Frontal Image Type in ISO/IEC 19794-5 clauses 8.2, 8.3, and 8.4.",
  "portrait_encoding": "base64",
  "portrait_content_type": "image/jpeg, image/jp2",
  "portrait_validation_max_size_bytes": "50000",
  "portrait_validation_min_width": "100",
  "portrait_validation_min_height": "100",
  "portrait_standards_iso_quality_clauses": "8.2, 8.3, 8.4",
  "portrait_standards_iso_quality_image_type": "Full Frontal Image Type",
  "portrait_standards_iso_format_exclusions_clauses": "8.1, 8.5",
  "portrait_standards_iso_format_exclusions_note": "SHALL NOT contain headers or blocks specified in clause 5, only JPEG image data",
  "portrait_data": "/9j/4AAQSkZJRgABAQE..."
}

Questions for Maintainers

1. Is this Flattened String Structure the recommended way to handle complex attributes like portraits given the current additionalProperties: string restriction?

2. Should we instead consider a Schema Update to allow attributeClaims to accept nested objects (JSON), which would better support the structured metadata suggested in previous comments ?

3. Could the portrait be promoted to a standard field within userClaims to avoid these mapping issues?

Goal

Establish a clear and consistent pattern for all Authentic Sources that need to provide biometric or complex binary data while remaining strictly compliant with the validated OpenAPI schema.