Session Date/Time: 02 Jul 2025 12:00

ASDF

Summary

The ASDF (A Semantic Definition Format) Working Group held a virtual interim to review open GitHub issues. Key discussions focused on addressing real-world implementation challenges with URI path handling, clarifying terminology, and ensuring consistency across the specification. Several issues were closed due to recent draft updates, while others require further discussion or specific actions. A hackathon for NIPY is planned for the upcoming Madrid face-to-face meeting.

Key Discussion Points

Context Types and Content Format Quality (Issue 1):
- Discussion initiated in a previous interim regarding using content format quality instead of fixed values for context types in the SDF model.
- This issue remains open and will be reviewed before the next face-to-face meeting.
SDF Global Names and URI Path Separator (Issue 2):
- Earlier NIPY implementations encountered issues with proxies (e.g., Jetty) incorrectly handling percent-encoded reserved characters (specifically /) in URI paths, leading to 400 errors (ambiguous URI path separator).
- Despite RFC 3986 and RFC 9110 clearly stating that percent-encoded reserved characters should not be normalized, many real-world implementations and security practices default to disallowing them due to widespread path traversal vulnerabilities and security concerns.
- This creates a hurdle for NIPY implementations, leading to difficult security discussions.
- Proposed Solution (Draft 8): Move the global name parameter from the URI path to the query string to avoid these issues entirely. This might be a stylistic change but is seen as the most feasible workaround.
- Discussion: Carsten noted the difficulty of addressing "damage" caused by misbehaving implementations and plans to engage the HTTP API WG for fact-finding on real-world capabilities and perceptions. Elliot expressed frustration but supported the proposed workaround for ASDF, suggesting broader IETF documentation of this issue via HTTP API WG or an independent stream. Elliot also called for participation from implementers like Tomcat and Jetty in the discussion.
- The issue remains open to allow further discussion and fact-finding within the HTTP API WG.
Get ID Property and SKIM Integration (Issue 3):
- Discussion around specifying the use of device identifiers (UUIDs) in NIPY, particularly how they are obtained via SKIM (Simple Cloud Identity Management).
- It was clarified that UUIDs are typically generated by a SKIM server. NIPY clients need to know the device's UUID to interact with it.
- While SKIM is a logical mechanism for onboarding devices, NIPY should not be strictly mandatory on SKIM. An applicability statement is needed to clarify NIPY's relationship with SKIM for device discovery and UUID provision.
- This issue remains open for further investigation and feedback from SKIM experts.
IANA Considerations (Issue 4):
- Tracking item to ensure IANA considerations are properly addressed in the draft.
- No specific action taken during this call, remains open.
NIPY Action APIs with Embedded Protocol Mapping (Issue 5):
- Previous discussions led to the decision to remove "embedded protocol mapping" from the specification.
- The text and examples have been updated to reflect this.
- Decision: This issue is closed.
SDF Uppercase (Issue 6):
- Editorial question regarding consistent casing of "SDF" (e.g., uppercase vs. lowercase) within the document text.
- Carsten offered to help define simple rules for consistent casing.
- The issue remains open.
X-Request-ID (Issue 7):
- NIPY previously included an X-Request-ID header for unique request identification.
- It was decided to remove this from the spec as X-Request-ID is not an official HTTP header, although implementations are free to use it if they wish.
- The relevant PR (PR 90) for this change has been merged.
- Decision: This issue is closed.
Async Responses (HTTP Status Code) (Issue 8):
- Corrected the HTTP status code for asynchronous responses from 200 to 202 (Accepted), which should include a Location header pointing to a status API endpoint.
- Discussion on whether there's a specific IETF specification for this asynchronous pattern (202 Accepted + Location header) or if it's a well-known industry pattern.
- The issue remains open to investigate if HTTP API WG has guidance on this.
NIPY Gateway Separation / UUID Spec (RFC9072) (Issue 9):
- Clarified that UUIDs for devices are typically generated by a SKIM server.
- NIPY does not strictly mandate SKIM, but clients must somehow learn the device's UUID (either via SKIM or out-of-band).
- An applicability statement for NIPY's interaction with SKIM for UUID provision is suggested.
- This issue remains open.
Well-Known URI (Issue 10):
- Still needs work. Remains open.
JSON vs. CBOR (Issue 11):
- NIPY uses JSON for RESTful APIs and CBOR for MQTT data.
- Justification: JSON is standard for REST; CBOR provides binary efficiency for MQTT data, avoiding base64 encoding that would be necessary with JSON. This aligns with existing ecosystem patterns.
- Discussion: Acknowledged the added complexity for developers needing to handle both formats. Carsten noted that adding choices increases deployment cost. The current approach reflects industry practice.
- Will add more context to the document explaining the rationale. Remains open for further review.
Authorization (Issue 12):
- Discussion on how authorization (e.g., which client can control which device feature) is handled.
- SKIM's "endpoint apps" extension can define application-specific permissions (e.g., separate apps for control commands vs. data streaming).
- Needs to add forward references to the SKIM RFC and the device model draft in NIPY's security considerations.
- Remains open.
Figure 2 Diagram Orientation (Issue 13):
- Michael suggested flipping the orientation of Figure 2.
- Elliot suggested borrowing the exact diagram from the updated SKIM draft for consistency across documents and using the aa-svg tool for SVG generation.
- Decision: Adopt the diagram from the SKIM draft.
"Interprets, decodes or modifies these payloads" Statement (Issue 14):
- The current text is incorrect; NIPY does interpret and potentially modify payloads via SDF.
- Needs to be updated to reflect current functionality. Remains open.
Onboarding vs. Registration Terminology (Issue 15):
- Discussed consistent use of "onboarding" (for devices) and "registration" (for SDF models).
- Michael advocated for lowering cognitive load and aligning with established ecosystem terminology, offering to provide a reference to a T2G document on IoT terminology.
- Remains open for review and proposed updates.
Scope vs. Motivation/Opportunity Sections (Issue 16):
- Suggestion to split the current "Scope" section into two: "Scope" (defining what the document does/doesn't do) and "Motivation/Opportunity" (explaining the problem NIPY solves and the existing industry context of gateways).
- This would help explain the "why" of the specification. Remains open.
Implementation Status Section (Issue 17):
- Carsten suggested adding an "Implementation Status" section (as per RFC guidelines, to be deleted before publication).
- This section can document existing implementations (even non-standard ones) to demonstrate the real-world context and motivation behind the NIPY specification, which is valuable for ISG review.
- Will be incorporated. Remains open.
Problem Details (Issue 18):
- Updated in Draft 7 to use IANA-registered types instead of custom NIPY status types.
- Decision: This issue is closed.
List Return Type (Issue 19):
- Adjusted to return a list type.
- Decision: This issue is closed.
SDF Model for Firmware Updates (Issue 20):
- Clarified that new SDF models are registered upon firmware updates, and old models' reference counts will naturally drop to zero as devices update.
- Decision: This issue is closed.

Decisions and Action Items

Decisions

The issue "NIPY Action APIs with embedded protocol mapping" (Issue 5) is closed.
The issue "X-Request-ID" (Issue 7) is closed.
The issue "Problem Details" (Issue 18) is closed.
The issue "List Return Type" (Issue 19) is closed.
The issue "SDF Model for Firmware Updates" (Issue 20) is closed.
Figure 2 will be updated by adopting the diagram from the latest SKIM draft for consistency, using the aa-svg tool.

Action Items

Chairs/Rohit: Review "context types and content format quality" (Issue 1) before the face-to-face meeting.
Carsten: Continue fact-finding and discussion with the HTTP API WG regarding percent-encoded slashes (Issue 2) for approximately two more weeks.
Elliot: Monitor the HTTP API list for discussions on percent-encoded slashes, prepare to write an independent stream document if needed, and encourage participation from Tomcat/Jetty implementers.
Rohit/Bart: Track the HTTP API list for the percent-encoded slashes issue.
Rohit: Gather feedback on SKIM integration for device ID property (Issue 3) by the next interim.
Rohit: Address IANA considerations (Issue 4).
Carsten: Provide guidance or rules for consistent "SDF" casing in the document text (Issue 6).
Rohit: Investigate if the HTTP API WG has a specification or well-defined pattern for asynchronous HTTP responses (202 Accepted + Location header) (Issue 8).
Rohit: Add an applicability statement to the document clarifying NIPY's reliance on SKIM for UUIDs or alternative mechanisms (Issue 9).
Rohit: Work on the "well-known URI" issue (Issue 10).
Rohit: Add detailed context and justification in the document for using both JSON and CBOR (Issue 11).
Rohit: Add references to the SKIM RFC and the device model draft within NIPY's security considerations, specifically for authorization (Issue 12).
Rohit: Update the text regarding NIPY's interpretation of payloads via SDF (Issue 14).
Michael: Provide a reference to the T2G document on IoT terminology for "onboarding vs. registration" (Issue 15).
Rohit: Propose updates for the "onboarding vs. registration" terminology based on T2G document (Issue 15).
Rohit: Clarify and potentially reorganize the "Scope" and "Motivation/Opportunity" sections (Issue 16).
Rohit/Chairs: Incorporate an "Implementation Status" section into the draft (Issue 17).

Next Steps

Continue discussions on remaining open issues, particularly the URI path separator issue with the HTTP API WG.
The next virtual interim will be scheduled during the upcoming IETF face-to-face meeting in Madrid.
A NIPY hackathon is registered for the Madrid meeting, and implementers are encouraged to participate.
The working group will consider holding virtual interims monthly, potentially shifting the start time by 30 minutes to accommodate different time zones, to be confirmed at the Madrid meeting.