Open APIs

Hi

if I expand an EntityRef using depth and expand directives, should the returned @type be changed from EntityRef to Entity, or should it remain EntityRef with additional fields?

Hi

if I expand an EntityRef using depth and expand directives, should the returned @type be changed from EntityRef to Entity, or should it remain EntityRef with additional fields?

That is an interesting question. 

This is what we have done in our implementations. As an example for an "expand": "@type": 'AccountRef' becomes "@type": "Account" and where there was previously an EntityRef object, we now display the entity.

But this leads to the next relevant question: Do the OAS API specifications allow this at all? The "@type" will play a much more important role as a discriminator in the future. From the OAS perspective, an expand would then only be permitted if both an EntityRef and an Entity are possible at the position. However, this is only possible for GET operations and not for other operations.

I've never really checked the v5 APIs for the expand feature.

Above all, multiple nested expands are also possible (via depth). In my example with AccountRef and Account: If Account also uses EntityRef patterns again, the schema definition of Account must also allow its refs to be "resolved" in turn.

Greetings,
Jan

Hi

if I expand an EntityRef using depth and expand directives, should the returned @type be changed from EntityRef to Entity, or should it remain EntityRef with additional fields?

Valid concern.  I have raised a JIRA ticket against this at [AP-6841] Consistency when using expand/depth directive alongside the strongly-typed Gen5 schemas - TM Forum JIRA

------------------------------
Dan d'Albuquerque
Entronica Company Limited

Original Message:
Sent: Jun 12, 2025 02:33
From: Jan Lemmermann
Subject: Depth/Expand - does it change ref to value?

That is an interesting question. 

This is what we have done in our implementations. As an example for an "expand": "@type": 'AccountRef' becomes "@type": "Account" and where there was previously an EntityRef object, we now display the entity.

But this leads to the next relevant question: Do the OAS API specifications allow this at all? The "@type" will play a much more important role as a discriminator in the future. From the OAS perspective, an expand would then only be permitted if both an EntityRef and an Entity are possible at the position. However, this is only possible for GET operations and not for other operations.

I've never really checked the v5 APIs for the expand feature.

Above all, multiple nested expands are also possible (via depth). In my example with AccountRef and Account: If Account also uses EntityRef patterns again, the schema definition of Account must also allow its refs to be "resolved" in turn.

Greetings,
Jan

------------------------------
Jan Lemmermann
OSS Lead Architect
EWE TEL GmbH

Original Message:
Sent: Jun 11, 2025 04:25
From: Piotr Ledwoń
Subject: Depth/Expand - does it change ref to value?

Hi

if I expand an EntityRef using depth and expand directives, should the returned @type be changed from EntityRef to Entity, or should it remain EntityRef with additional fields?

------------------------------
Piotr Ledwoń
Suntech S.A.
------------------------------

Is it allowed to use RefOrValue in place of Ref if expansion is supported for a given field?

Also, who has access to view those Jira tickets? I assume they are not publicly accessible since I can't view them. Is  there no read-only view options for regular members so that we know in which direction the API development goes?

------------------------------
Piotr Ledwoń
Suntech S.A.
------------------------------

Original Message:
Sent: Jun 12, 2025 02:54
From: Dan d'Albuquerque
Subject: Depth/Expand - does it change ref to value?

Valid concern.  I have raised a JIRA ticket against this at [AP-6841] Consistency when using expand/depth directive alongside the strongly-typed Gen5 schemas - TM Forum JIRA

------------------------------
Dan d'Albuquerque
Entronica Company Limited

Original Message:
Sent: Jun 12, 2025 02:33
From: Jan Lemmermann
Subject: Depth/Expand - does it change ref to value?

That is an interesting question. 

This is what we have done in our implementations. As an example for an "expand": "@type": 'AccountRef' becomes "@type": "Account" and where there was previously an EntityRef object, we now display the entity.

But this leads to the next relevant question: Do the OAS API specifications allow this at all? The "@type" will play a much more important role as a discriminator in the future. From the OAS perspective, an expand would then only be permitted if both an EntityRef and an Entity are possible at the position. However, this is only possible for GET operations and not for other operations.

I've never really checked the v5 APIs for the expand feature.

Above all, multiple nested expands are also possible (via depth). In my example with AccountRef and Account: If Account also uses EntityRef patterns again, the schema definition of Account must also allow its refs to be "resolved" in turn.

Greetings,
Jan

------------------------------
Jan Lemmermann
OSS Lead Architect
EWE TEL GmbH

Original Message:
Sent: Jun 11, 2025 04:25
From: Piotr Ledwoń
Subject: Depth/Expand - does it change ref to value?

Hi

if I expand an EntityRef using depth and expand directives, should the returned @type be changed from EntityRef to Entity, or should it remain EntityRef with additional fields?

------------------------------
Piotr Ledwoń
Suntech S.A.
------------------------------

Is it allowed to use RefOrValue in place of Ref if expansion is supported for a given field?

Also, who has access to view those Jira tickets? I assume they are not publicly accessible since I can't view them. Is  there no read-only view options for regular members so that we know in which direction the API development goes?

------------------------------
Piotr Ledwoń
Suntech S.A.

Original Message:
Sent: Jun 12, 2025 02:54
From: Dan d'Albuquerque
Subject: Depth/Expand - does it change ref to value?

Valid concern.  I have raised a JIRA ticket against this at [AP-6841] Consistency when using expand/depth directive alongside the strongly-typed Gen5 schemas - TM Forum JIRA

------------------------------
Dan d'Albuquerque
Entronica Company Limited

Original Message:
Sent: Jun 12, 2025 02:33
From: Jan Lemmermann
Subject: Depth/Expand - does it change ref to value?

That is an interesting question. 

This is what we have done in our implementations. As an example for an "expand": "@type": 'AccountRef' becomes "@type": "Account" and where there was previously an EntityRef object, we now display the entity.

But this leads to the next relevant question: Do the OAS API specifications allow this at all? The "@type" will play a much more important role as a discriminator in the future. From the OAS perspective, an expand would then only be permitted if both an EntityRef and an Entity are possible at the position. However, this is only possible for GET operations and not for other operations.

I've never really checked the v5 APIs for the expand feature.

Above all, multiple nested expands are also possible (via depth). In my example with AccountRef and Account: If Account also uses EntityRef patterns again, the schema definition of Account must also allow its refs to be "resolved" in turn.

Greetings,
Jan

------------------------------
Jan Lemmermann
OSS Lead Architect
EWE TEL GmbH

Original Message:
Sent: Jun 11, 2025 04:25
From: Piotr Ledwoń
Subject: Depth/Expand - does it change ref to value?

Hi

if I expand an EntityRef using depth and expand directives, should the returned @type be changed from EntityRef to Entity, or should it remain EntityRef with additional fields?

------------------------------
Piotr Ledwoń
Suntech S.A.
------------------------------