mdn
Documentation for HTML Model element (take 2)
( This is a rebuild of the Model element PR from https://github.com/mdn/content/pull/39710 )
Preface to the new PR
This branch is a clean rebuild of the substantive content about the HTML Model element from the earlier PR at https://github.com/mdn/content/pull/39710
where I had alterations to a .lock file. Since I'm not familiar enough with Git to revert one single file in the overall process, I thought it would be best to start fresh. Apologies for the clutter!
Description
This PR adds API documentation about the proposed HTML Model element, a browser-native feature for the in-line display of 3D content. It includes illustrations of some core concepts like perspective, lighting and appropriate file formats.
Motivation
The Model element is a totally new web feature and it'll be exceptionally difficult to add documentation in a piecemeal fashion. I'm hoping that this covers the core concepts enough to author new pages from, and matches the MDN house style well enough that other folks can improve them to the point that they are real!
Additional details
I am submitting provisional documentation for the HTML model element, a feature that is the major source of discussion in the W3C Immersive Web CG (https://github.com/immersive-web/model-element/ ) and which is available as a feature preview in visionOS 2.4. I am an editor of the specification and have been facilitating the discussion around it.
While the specification doesn’t have a lot of detail, the API in visionOS is based on the consensus discussion in the CG, and is described in the Model Element explainer: (https://github.com/immersive-web/model-element/blob/main/explainer.md )
There is also a WebGL/WebXR-based interactive explainer demo available here: https://immersive-web.github.io/model-element/explainer_demo.html
We also have public samples being contributed by multiple browser vendors in the model element samples repository. https://immersive-web.github.io/model-element-samples/
We have previously submitted related additions to the WHATWG HTML specification as via an introductory issue and initial PR for the specification stub. https://github.com/whatwg/html/issues/10901 https://github.com/whatwg/html/pull/11191
Related issues and pull requests
WHATWG/HTML
- https://github.com/whatwg/html/issues/10901
- https://github.com/whatwg/html/pull/11191
the Web Platform Tests repository
- https://github.com/web-platform-tests/wpt/pull/51667
HTML-ARIA
- https://github.com/w3c/aria/issues/2508
Preview URLs (20 pages)
/en-US/docs/Web/API/HTMLModelElement/autoplay/en-US/docs/Web/API/HTMLModelElement/boundingBoxCenter/en-US/docs/Web/API/HTMLModelElement/boundingBoxExtents/en-US/docs/Web/API/HTMLModelElement/currentSrc/en-US/docs/Web/API/HTMLModelElement/currentTime/en-US/docs/Web/API/HTMLModelElement/duration/en-US/docs/Web/API/HTMLModelElement/entityTransform/en-US/docs/Web/API/HTMLModelElement/environmentMapReady/en-US/docs/Web/API/HTMLModelElement/environmentMap/en-US/docs/Web/API/HTMLModelElement/height/en-US/docs/Web/API/HTMLModelElement/loop/en-US/docs/Web/API/HTMLModelElement/pause/en-US/docs/Web/API/HTMLModelElement/paused/en-US/docs/Web/API/HTMLModelElement/play/en-US/docs/Web/API/HTMLModelElement/playbackRate/en-US/docs/Web/API/HTMLModelElement/ready/en-US/docs/Web/API/HTMLModelElement/stageMode/en-US/docs/Web/API/HTMLModelElement/width/en-US/docs/Web/API/HTMLModelElement/en-US/docs/Web/HTML/Reference/Elements/model
Flaws (1)
Note! 19 documents with no flaws that don't need to be listed. 🎉
URL: /en-US/docs/Web/HTML/Reference/Elements/model
Title: <model>: The HTML Model element
Flaw count: 1
- broken_links:
Can't resolve /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/model_role
External URLs (13)
URL: /en-US/docs/Web/API/HTMLModelElement/boundingBoxCenter
Title: HTMLModelElement: boundingBoxCenter property
- https://en.wikipedia.org/wiki/Center_of_mass (1 time) (Note! This may be a new URL 👀)
- https://en.wikipedia.org/wiki/Skeletal_animation (1 time) (Note! This may be a new URL 👀)
URL: /en-US/docs/Web/API/HTMLModelElement/boundingBoxExtents
Title: HTMLModelElement: boundingBoxExtents property
- https://en.wikipedia.org/wiki/Center_of_mass (1 time) (Note! This may be a new URL 👀)
- https://en.wikipedia.org/wiki/Skeletal_animation (1 time) (Note! This may be a new URL 👀)
URL: /en-US/docs/Web/API/HTMLModelElement/environmentMap
Title: HTMLModelElement: environmentMap property
- https://en.wikipedia.org/wiki/Equirectangular_projection (1 time) (Note! This may be a new URL 👀)
URL: /en-US/docs/Web/API/HTMLModelElement/playbackRate
Title: HTMLModelElement: playbackRate property
- https://en.wikipedia.org/wiki/Double-precision_floating-point_format (1 time) (Note! This may be a new URL 👀)
URL: /en-US/docs/Web/HTML/Reference/Elements/model
Title: <model>: The HTML Model element
- https://en.wikipedia.org/wiki/Cartesian_coordinate_system (1 time) (Note! This may be a new URL 👀)
- https://en.wikipedia.org/wiki/Equirectangular_projection (1 time) (Note! This may be a new URL 👀)
- https://en.wikipedia.org/wiki/Identity_matrix (1 time) (Note! This may be a new URL 👀)
- https://en.wikipedia.org/wiki/OpenEXR (1 time) (Note! This may be a new URL 👀)
- https://en.wikipedia.org/wiki/RGBE_image_format (1 time) (Note! This may be a new URL 👀)
- https://openusd.org/release/spec_usdz.html (1 time) (Note! This may be a new URL 👀)
- https://www.khronos.org/gltf/ (1 time) (Note! This may be a new URL 👀)
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
I've talked about this PR with some of the other MDN maintainers, and we don't think this feature is ready to be documented on MDN yet (and therefore isn't ready for a review yet). We use two main criteria for deciding when a feature is ready: the extent to which it's implemented in browsers, and the extent to which there's a stable, detailed, specification for it.
The key place these criteria are described is https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/What_we_write#when_we_document_a_new_technology . In particular, this lists the following as a reason not to document a feature:
It doesn't have a specification or the specification is a rough note that looks liable to change,
This seems applicable to the spec as it stands: https://immersive-web.github.io/model-element/. I know the PR description here says:
While the specification doesn’t have a lot of detail, the API in visionOS is based on the consensus discussion in the CG, and is described in the Model Element explainer: (https://github.com/immersive-web/model-element/blob/main/explainer.md )
...but the explainer is also not detailed enough to function as a spec.
It's my understanding that this is shipping in a technical preview of VisionOS. AFAIK only shipping in a technical preview doesn't count as "shipping" for our purposes, because it doesn't represent evidence that the feature is stable.
The underlying reason for these criteria is that we don't want to document things that are likely to change a lot or potentially not be adopted at all. When we document things too early, one of these things happens quite often.
I think the best plan would be to mark this PR a draft, and continue to update it as the specification matures, and ask for a review when the specification is stable and it is shipping.
Thank you for the reasoned response, @wbamberg. I’ll aim to revisit this if/when a browser releases the feature and we have a better basis to reason about what the spec needs to clarify.
HTML Model element is now available by default in visionOS 26! Now that more folks will actually be able to see it, I believe we'll be able to start negotiating and filling out specification-class descriptions for multiple vendors to agree on.
@wbamberg I'm open to your recommendations as to whether we add detail to MDN piecemeal, as it's added to a spec, or if we can provide the current state as-is and revise/refine once other vendors are in a position to help us define mandatory algorithm structures etc.
@wbamberg I'm open to your recommendations as to whether we add detail to MDN piecemeal, as it's added to a spec, or if we can provide the current state as-is and revise/refine once other vendors are in a position to help us define mandatory algorithm structures etc.
I think it makes sense to wait until the specification is stable and detailed and then file a PR to document the whole thing.
We need to set a deadline for this: if the API does not meet our documentation criteria by then, then we need to close this PR until it does. When would be good? I'm thinking when this PR becomes 6 months old, so Dec 5th.
I just noticed this comment:
Given the complexity of this feature, we expect the final PR to be quite large and probably take about 1-2 years to complete Stage 3 before sending it over as pull request to the main spec.
So, we would be expecting at least 1-2 years before even a draft spec is available, after which there's still an unknown timespan for editors review, during which time it's entirely possible for the feature to change. So I don't think it's productive for MDN to wait for that. FYI MDN encourages the spec PR to be merged before you start working on content; it's definitely fine for you to work on this in advance but we won't want to allocate resources for it, and a place in the PR queue counts as a resource. Temporal has gone down that path: its initial docs were written in around 2018, 7 years before its official release, and during that time it sat as a branch in a forked repo and the main repo allocates zero resources for it.