Difference: DocRegExt10RFC (1 vs. 9)

DocRegExt Proposed Recommendation: Request for Comments

DocRegExt is a VOResource extension for registering documents useful for teaching and learning the Virtual Observatory. It re-uses common VODataService (CatalogResource) metadata and adds the concept of an edition; for the VO this is somewhat new because we care about national languages and linking source code.

The latest version of DocRegExt can be found at:

• http://ivoa.net/documents/DocRegExt/

Minor changes in response to RFC comments will be reflected in the build at https://docs.g-vo.org/DocRegExt.pdf; reviewers may want to look at this copy.

You can also use the github repo for commenting: https://github.com/ivoa-std/DocRegExt

Reference Interoperable Implementations

There are existing DocRegExt records from multiple authorities. Try

select ivoid from rr.resource
where res_type='doc:document'

on a RegTAP service (this gives 45 records at this time). See, for instance, https://dc.g-vo.org/I/ivo%3A//edu.euro-vo.org/tutorials/08_m1_distance as an example for a multi-language document, or https://dc.g-vo.org/I/ivo%3A//org.gavo.dc/tutreg/gavo_pyvocourse/rec for a record with links to a source control system.

On the consumer side, there is the register of VO Text Treasures https://dc.g-vo.org/VOTT.

See also http://svn.ari.uni-heidelberg.de/svn/gavo/hdinputs/vott/res/to-dalia-if.py (make sure your browser does not change that to https or you will be asked for credentials); this is a pyVO script that turns DocRegExt metadata as ingested into the Registry into the schema of the cross-discipline search engine at https://dalia.education. This is in active use for feeding them our material.

Implementations Validators

There is a schema file; use any schema validator on instance documents. There is no further, “semantic” validation so far. I would in particularly like to flag everything that has only one sentence in its description as in need of more love, but as the details of such an endeavour are tricky, I doubt that it will ever happen.

Comments from the IVOA Community during RFC/TCG review period: Nov 15,2025 – Jan 15, 2026

The comments from the TCG members during the RFC/TCG review should be included in the next section.

In order to add a comment to the document, please edit this page and add your comment to the list below in the format used for the example (include your Wiki Name so that authors can contact you for further information). When the author(s) of the document have considered the comment, they will provide a response after the comment.

Additional discussion about any of the comments or responses can be conducted on the WG mailing list. However, please be sure to enter your initial comments here for full consideration in any future revisions of this document

• Sample comment by WikiName
  • Response (by WikiName)

Comments from TCG member during the RFC/TCG Review Period: Nov 15. 2025 – Jan 15, 2026

WG chairs or vice chairs must read the Document, provide comments if any (including on topics not directly linked to the Group matters) or indicate that they have no comment.

IG chairs or vice chairs are also encouraged to do the same, althought their inputs are not compulsory.

TCG Chair & Vice Chair

Applications Working Group

There are no major concerns as far as Apps WG goes. The document is understandable in use and purpose. Typos suggestions have been submitted in a separate PR.

• Merged, thanks! -- MarkusDemleitner - 2026-01-26

Following there are few minor comments:

- have you considered EduRegExt as the name?

• Yes, and we felt it might narrow the scope too much; this is also intended for material, say, accompanying data releases and addressing researchers; while technicaly, that might be called education, we fear both producers and consumers might be slightly offended by that term -- MarkusDemleitner - 2026-01-26
  
  
  

• • My comments would also be around the naming, both DocRegExt and the resource type. We primarily talking about tutorials, so it would be nice to have a naming scheme that reflects it. (E.g. when you say document I do think of a standard document or pdf and not educational/tutorial material). Maybe it would be worth having both? E.g. "document" could be the DR describing pdf and the "tutorial" could be the tutorials? The formal will be universal for the data release, while the latter is likely tied to specific tools. -- Brigitta 2026-01-27
    (as for specific examples, I'm thinking that this document (https://irsa.ipac.caltech.edu/data/SPHEREx/docs/SPHEREx_Expsupp_QR.pdf) is the DR accompaning material with `doc:Document` resource type; while a python tutorial notebook like this https://github.com/Caltech-IPAC/irsa-tutorials/blob/main/tutorials/spherex/spherex_psf.md would have a `doc:Tutorial` resource type.)
    • Well, I've not looked at it this way, but if we ever want to register documentation resources of this sort, the name DocRegExt would make it a good umbrella for that, too. However, your concrete example should probably be the referenceURL for the resource corresponding to that specific data collection (or perhaps linked from it). Even if you ended up registering multiple resources for it, the way to go about it would be having a perhaps DataResource record for which this would be the referenceURL and holding together the compound services using HasPart and IsPartOf relationships. -- MarkusDemleitner - 2026-01-29

- we are happy to see the date: Inspected in the document but could it recommend using the field in orderBy queries to give priority to newer or recently Inspected records over old outdated ones?

• VOTT, for instance, has several sort modes, and I think the "currency" of a piece of documentation is just one of many criteria to assess its relevance to a given situation. So, while I generally like implementation advice of this sort (and usually get talked out of it by Mark T.), I think here it would not help implementors much -- MarkusDemleitner - 2026-01-26

- should multiple major versions of document in a language be accepted? Or that is just a consequence of the lack of a mechanism to prevent that.

• A single publisher should only put out a single version of a document at any one time; it's bad enough that we cannot keep the various translations in sync. If a different publisher really thinks a previous version should be preserved for whatever reason, they can add a second resource record. But I'd try to talk them out of it -- MarkusDemleitner - 2026-01-26

- another concern with these resources that they could outdate really quick. Is there any plans for any metadata fields that either indicate the last date it was tested, or some other indicator that distinguish between a maintained resource or something dumped in the registry and then never revisited? (I think we can agree that a python notebook tutorial from 5-10 years ago is not to be expected to just work out of the box right now -- how can we ensure the registry results won't be dominated by such outdated resources?).

• The sad truth is we can't, not by technical measures anyway. Things stay current if people care about them, and they rust when they don't. date/@role=inspected at least lets people express that they're maintaining the tutorials, and that way people can at least sort the records such that maintained material ends up near the top. Beyond that... well, the VO community as a whole may one day decide to do resource triaging. When they do, I think DocRegExt records will be triaged much the way other records are. -- MarkusDemleitner - 2026-01-29

Data Access Layer Working Group

Data Model Working Group

Distributed Services & Protocols Working Group

In general, this spec is not impacting DSP, so it is approved from our side.

Just some comments that could help to improve it for consideration by the authors:

1 - Naming; DocRegExt vs tutorials/education (echoing Brigitta’s point)

“Document” sounds like standards or PDFs, not tutorials/notebooks. Users searching for “tutorials” won’t naturally think “document”.

I think we do not need to rename the extension (DocRegExt is fine as an umbrella), but improve semantics. Keep extension: DocRegEx resource: doc:Document

but add a controlled vocabulary for subtype, e.g., tutorial, notebook, course, walkthrough, reference-manual, release-doc,...

Registry Working Group

Semantics Working Group

Data Curation & Preservation Interest Group

DCP feedbacks.

• listing tools is cool, but as free text, they sound as keywords :(
  This distorts the meaning of linked data in terms of "relationships".
  
  Suggest: (I like the idea to attach tools) it would need an additional step consisting to register tools in registry. A tool-resource with URLs to dowload softwares, documentation(s), examples... it would be nice ?
  
  
  • Absolutely. I've been advocating this sort of thing for a long time, but considerations of registering software have always led to unproductive discussions. Hence, I'd rather not build upon it here. What I could imagine is to reommend ascl identifiers as relatedResource's clear text. Or should we say "put ascl.net/nnnn.mmm into altIdentifier"? -- MarkusDemleitner - 2026-01-26

• Adding type to Documents & tutorials (metadata existing in DCAT or DataCite)
  
  Suggest: add the format of the resource: application/pdf, text/html (WEB service), application/x-ipynb+json (notebook)
  
  For instance, adding formats (such as DataCite) or adding a new interface type (like WebBrower) (eg: xsi:type="vr:WebDocument" and "vr:resultType")
  Example: <interface xsi:type="vr:WebDocument"><resultType>application/x-ipynb+json</resultType></interface>
  • Hm... This isn't resource-level metadata, because it's conceivable that one language comes in in Open Document and another language comes in PDF. And then it's likely that we'll see compound material: PDF plus python source code, say, or perhaps a longer narrative in a PDF and an accompanying notebook. In short: I'd need a good case where having this information would actually influence the discovery process. Until then, I'd tend to believe that if someone really wants to see some content, they won't care too much what format it's in. -- MarkusDemleitner - 2026-01-26

Other feedbacks

• Documents and Resources linking
  The Recommendation allows to create a "Document" with metadata that lists the resources used (we have in CDS this type of resources in different format).
  The recommendation doesn't provide a "reverse" way to add documentation on existing published resource (we have in VizieR). This Document could have an ivoid or an external URL.
  
  eg: The resource ivo://cds.vizier/J/AJ/161/36 has a notebook which is available in the landing page:
  https://cdsarc.cds.unistra.fr/vizier/notebook.gml?source=J/AJ/161/36
  
  Suggest: adding relation IsDocumentedBy (from DataCite) or usedInDocument (invented?)
  an alternative would consist to use interface (enables to specify format with "vr:resultType")

• • I wonder whether IsSupplementedBy isn't what this is about. See p. 6, where we say that tutorials "specifically introducing one or more services should define IsSupplementTo relationships". I think this is the situation that you describe here, and then we'd have this natural inversion. Should we stress this point a bit more? -- MarkusDemleitner - 2026-01-26

Education Interest Group

High Energy Interest Group

Knowledge Discovery Interest Group

Operations Interest Group

Radio Astronomy Interest Group

Solar System Interest Group

Time Domain Interest Group

Standards and Processes Committee

TCG Vote : Jan 1, 2026 – Jan 15, 2026

If you have minor comments (typos) on the last version of the document please indicate it in the Comments column of the table and post them in the TCG comments section above with the date.

<!--
* Set ALLOWTOPICRENAME = TWikiAdminGroup
-->

DocRegExt Proposed Recommendation: Request for Comments

DocRegExt is a VOResource extension for registering documents useful for teaching and learning the Virtual Observatory. It re-uses common VODataService (CatalogResource) metadata and adds the concept of an edition; for the VO this is somewhat new because we care about national languages and linking source code.

The latest version of DocRegExt can be found at:

Reference Interoperable Implementations

There are existing DocRegExt records from multiple authorities. Try

select ivoid from rr.resource
where res_type='doc:document'

Implementations Validators

There is a schema file; use any schema validator on instance documents. There is no further, “semantic” validation so far. I would in particularly like to flag everything that has only one sentence in its description as in need of more love, but as the details of such an endeavour are tricky, I doubt that it will ever happen.

Comments from the IVOA Community during RFC/TCG review period: Nov 15,2025 – Jan 15, 2026

The comments from the TCG members during the RFC/TCG review should be included in the next section.

In order to add a comment to the document, please edit this page and add your comment to the list below in the format used for the example (include your Wiki Name so that authors can contact you for further information). When the author(s) of the document have considered the comment, they will provide a response after the comment.

Additional discussion about any of the comments or responses can be conducted on the WG mailing list. However, please be sure to enter your initial comments here for full consideration in any future revisions of this document

• Sample comment by WikiName
  • Response (by WikiName)

Comments from TCG member during the RFC/TCG Review Period: Nov 15. 2025 – Jan 15, 2026

WG chairs or vice chairs must read the Document, provide comments if any (including on topics not directly linked to the Group matters) or indicate that they have no comment.

IG chairs or vice chairs are also encouraged to do the same, althought their inputs are not compulsory.

TCG Chair & Vice Chair

Applications Working Group

There are no major concerns as far as Apps WG goes. The document is understandable in use and purpose. Typos suggestions have been submitted in a separate PR.

• Merged, thanks! -- MarkusDemleitner - 2026-01-26

Following there are few minor comments:

- have you considered EduRegExt as the name?

• Yes, and we felt it might narrow the scope too much; this is also intended for material, say, accompanying data releases and addressing researchers; while technicaly, that might be called education, we fear both producers and consumers might be slightly offended by that term -- MarkusDemleitner - 2026-01-26
  
  
  

• • My comments would also be around the naming, both DocRegExt and the resource type. We primarily talking about tutorials, so it would be nice to have a naming scheme that reflects it. (E.g. when you say document I do think of a standard document or pdf and not educational/tutorial material). Maybe it would be worth having both? E.g. "document" could be the DR describing pdf and the "tutorial" could be the tutorials? The formal will be universal for the data release, while the latter is likely tied to specific tools. -- Brigitta 2026-01-27
    (as for specific examples, I'm thinking that this document (https://irsa.ipac.caltech.edu/data/SPHEREx/docs/SPHEREx_Expsupp_QR.pdf) is the DR accompaning material with `doc:Document` resource type; while a python tutorial notebook like this https://github.com/Caltech-IPAC/irsa-tutorials/blob/main/tutorials/spherex/spherex_psf.md would have a `doc:Tutorial` resource type.)

• VOTT, for instance, has several sort modes, and I think the "currency" of a piece of documentation is just one of many criteria to assess its relevance to a given situation. So, while I generally like implementation advice of this sort (and usually get talked out of it by Mark T.), I think here it would not help implementors much -- MarkusDemleitner - 2026-01-26

- should multiple major versions of document in a language be accepted? Or that is just a consequence of the lack of a mechanism to prevent that.

• A single publisher should only put out a single version of a document at any one time; it's bad enough that we cannot keep the various translations in sync. If a different publisher really thinks a previous version should be preserved for whatever reason, they can add a second resource record. But I'd try to talk them out of it -- MarkusDemleitner - 2026-01-26

- another concern with these resources that they could outdate really quick. Is there any plans for any metadata fields that either indicate the last date it was tested, or some other indicator that distinguish between a maintained resource or something dumped in the registry and then never revisited? (I think we can agree that a python notebook tutorial from 5-10 years ago is not to be expected to just work out of the box right now -- how can we ensure the registry results won't be dominated by such outdated resources?).

Data Access Layer Working Group

Data Model Working Group

Distributed Services & Protocols Working Group

Registry Working Group

Semantics Working Group

Data Curation & Preservation Interest Group

DCP feedbacks.

• • Absolutely. I've been advocating this sort of thing for a long time, but considerations of registering software have always led to unproductive discussions. Hence, I'd rather not build upon it here. What I could imagine is to reommend ascl identifiers as relatedResource's clear text. Or should we say "put ascl.net/nnnn.mmm into altIdentifier"? -- MarkusDemleitner - 2026-01-26

• Adding type to Documents & tutorials (metadata existing in DCAT or DataCite)
  
  Suggest: add the format of the resource: application/pdf, text/html (WEB service), application/x-ipynb+json (notebook)
  
  For instance, adding formats (such as DataCite) or adding a new interface type (like WebBrower) (eg: xsi:type="vr:WebDocument" and "vr:resultType")
  Example: <interface xsi:type="vr:WebDocument"><resultType>application/x-ipynb+json</resultType></interface>
  • Hm... This isn't resource-level metadata, because it's conceivable that one language comes in in Open Document and another language comes in PDF. And then it's likely that we'll see compound material: PDF plus python source code, say, or perhaps a longer narrative in a PDF and an accompanying notebook. In short: I'd need a good case where having this information would actually influence the discovery process. Until then, I'd tend to believe that if someone really wants to see some content, they won't care too much what format it's in. -- MarkusDemleitner - 2026-01-26

Other feedbacks

• Documents and Resources linking
  The Recommendation allows to create a "Document" with metadata that lists the resources used (we have in CDS this type of resources in different format).
  The recommendation doesn't provide a "reverse" way to add documentation on existing published resource (we have in VizieR). This Document could have an ivoid or an external URL.
  
  eg: The resource ivo://cds.vizier/J/AJ/161/36 has a notebook which is available in the landing page:
  https://cdsarc.cds.unistra.fr/vizier/notebook.gml?source=J/AJ/161/36
  
  Suggest: adding relation IsDocumentedBy (from DataCite) or usedInDocument (invented?)
  an alternative would consist to use interface (enables to specify format with "vr:resultType")

• • I wonder whether IsSupplementedBy isn't what this is about. See p. 6, where we say that tutorials "specifically introducing one or more services should define IsSupplementTo relationships". I think this is the situation that you describe here, and then we'd have this natural inversion. Should we stress this point a bit more? -- MarkusDemleitner - 2026-01-26

Education Interest Group

High Energy Interest Group

Knowledge Discovery Interest Group

Operations Interest Group

Radio Astronomy Interest Group

Solar System Interest Group

Time Domain Interest Group

Standards and Processes Committee

TCG Vote : Jan 1, 2026 – Jan 15, 2026

If you have minor comments (typos) on the last version of the document please indicate it in the Comments column of the table and post them in the TCG comments section above with the date.

DocRegExt Proposed Recommendation: Request for Comments

DocRegExt is a VOResource extension for registering documents useful for teaching and learning the Virtual Observatory. It re-uses common VODataService (CatalogResource) metadata and adds the concept of an edition; for the VO this is somewhat new because we care about national languages and linking source code.

The latest version of DocRegExt can be found at:

• http://ivoa.net/documents/DocRegExt/

Minor changes in response to RFC comments will be reflected in the build at https://docs.g-vo.org/DocRegExt.pdf; reviewers may want to look at this copy.

You can also use the github repo for commenting: https://github.com/ivoa-std/DocRegExt

Reference Interoperable Implementations

There are existing DocRegExt records from multiple authorities. Try

select ivoid from rr.resource
where res_type='doc:document'

on a RegTAP service (this gives 45 records at this time). See, for instance, https://dc.g-vo.org/I/ivo%3A//edu.euro-vo.org/tutorials/08_m1_distance as an example for a multi-language document, or https://dc.g-vo.org/I/ivo%3A//org.gavo.dc/tutreg/gavo_pyvocourse/rec for a record with links to a source control system.

On the consumer side, there is the register of VO Text Treasures https://dc.g-vo.org/VOTT.

See also http://svn.ari.uni-heidelberg.de/svn/gavo/hdinputs/vott/res/to-dalia-if.py (make sure your browser does not change that to https or you will be asked for credentials); this is a pyVO script that turns DocRegExt metadata as ingested into the Registry into the schema of the cross-discipline search engine at https://dalia.education. This is in active use for feeding them our material.

Implementations Validators

There is a schema file; use any schema validator on instance documents. There is no further, “semantic” validation so far. I would in particularly like to flag everything that has only one sentence in its description as in need of more love, but as the details of such an endeavour are tricky, I doubt that it will ever happen.

Comments from the IVOA Community during RFC/TCG review period: Nov 15,2025 – Jan 15, 2026

The comments from the TCG members during the RFC/TCG review should be included in the next section.

In order to add a comment to the document, please edit this page and add your comment to the list below in the format used for the example (include your Wiki Name so that authors can contact you for further information). When the author(s) of the document have considered the comment, they will provide a response after the comment.

Additional discussion about any of the comments or responses can be conducted on the WG mailing list. However, please be sure to enter your initial comments here for full consideration in any future revisions of this document

• Sample comment by WikiName
  • Response (by WikiName)

Comments from TCG member during the RFC/TCG Review Period: Nov 15. 2025 – Jan 15, 2026

WG chairs or vice chairs must read the Document, provide comments if any (including on topics not directly linked to the Group matters) or indicate that they have no comment.

IG chairs or vice chairs are also encouraged to do the same, althought their inputs are not compulsory.

TCG Chair & Vice Chair

Applications Working Group

There are no major concerns as far as Apps WG goes. The document is understandable in use and purpose. Typos suggestions have been submitted in a separate PR.

• Merged, thanks! -- MarkusDemleitner - 2026-01-26

Following there are few minor comments:

- have you considered EduRegExt as the name?

• VOTT, for instance, has several sort modes, and I think the "currency" of a piece of documentation is just one of many criteria to assess its relevance to a given situation. So, while I generally like implementation advice of this sort (and usually get talked out of it by Mark T.), I think here it would not help implementors much -- MarkusDemleitner - 2026-01-26

- should multiple major versions of document in a language be accepted? Or that is just a consequence of the lack of a mechanism to prevent that.

• A single publisher should only put out a single version of a document at any one time; it's bad enough that we cannot keep the various translations in sync. If a different publisher really thinks a previous version should be preserved for whatever reason, they can add a second resource record. But I'd try to talk them out of it -- MarkusDemleitner - 2026-01-26

Data Access Layer Working Group

Data Model Working Group

Distributed Services & Protocols Working Group

Registry Working Group

Semantics Working Group

Data Curation & Preservation Interest Group

DCP feedbacks.

• listing tools is cool, but as free text, they sound as keywords :(
  This distorts the meaning of linked data in terms of "relationships".
  
  Suggest: (I like the idea to attach tools) it would need an additional step consisting to register tools in registry. A tool-resource with URLs to dowload softwares, documentation(s), examples... it would be nice ?
  
  
  • Absolutely. I've been advocating this sort of thing for a long time, but considerations of registering software have always led to unproductive discussions. Hence, I'd rather not build upon it here. What I could imagine is to reommend ascl identifiers as relatedResource's clear text. Or should we say "put ascl.net/nnnn.mmm into altIdentifier"? -- MarkusDemleitner - 2026-01-26

• Adding type to Documents & tutorials (metadata existing in DCAT or DataCite)
  
  Suggest: add the format of the resource: application/pdf, text/html (WEB service), application/x-ipynb+json (notebook)
  
  For instance, adding formats (such as DataCite) or adding a new interface type (like WebBrower) (eg: xsi:type="vr:WebDocument" and "vr:resultType")
  Example: <interface xsi:type="vr:WebDocument"><resultType>application/x-ipynb+json</resultType></interface>
  • Hm... This isn't resource-level metadata, because it's conceivable that one language comes in in Open Document and another language comes in PDF. And then it's likely that we'll see compound material: PDF plus python source code, say, or perhaps a longer narrative in a PDF and an accompanying notebook. In short: I'd need a good case where having this information would actually influence the discovery process. Until then, I'd tend to believe that if someone really wants to see some content, they won't care too much what format it's in. -- MarkusDemleitner - 2026-01-26

Other feedbacks

• Documents and Resources linking
  The Recommendation allows to create a "Document" with metadata that lists the resources used (we have in CDS this type of resources in different format).
  The recommendation doesn't provide a "reverse" way to add documentation on existing published resource (we have in VizieR). This Document could have an ivoid or an external URL.
  
  eg: The resource ivo://cds.vizier/J/AJ/161/36 has a notebook which is available in the landing page:
  https://cdsarc.cds.unistra.fr/vizier/notebook.gml?source=J/AJ/161/36
  
  Suggest: adding relation IsDocumentedBy (from DataCite) or usedInDocument (invented?)
  an alternative would consist to use interface (enables to specify format with "vr:resultType")

• • I wonder whether IsSupplementedBy isn't what this is about. See p. 6, where we say that tutorials "specifically introducing one or more services should define IsSupplementTo relationships". I think this is the situation that you describe here, and then we'd have this natural inversion. Should we stress this point a bit more? -- MarkusDemleitner - 2026-01-26

Education Interest Group

High Energy Interest Group

Knowledge Discovery Interest Group

Operations Interest Group

Radio Astronomy Interest Group

Solar System Interest Group

Time Domain Interest Group

Standards and Processes Committee

TCG Vote : Jan 1, 2026 – Jan 15, 2026

If you have minor comments (typos) on the last version of the document please indicate it in the Comments column of the table and post them in the TCG comments section above with the date.

<!--
* Set ALLOWTOPICRENAME = TWikiAdminGroup
-->

DocRegExt Proposed Recommendation: Request for Comments

DocRegExt is a VOResource extension for registering documents useful for teaching and learning the Virtual Observatory. It re-uses common VODataService (CatalogResource) metadata and adds the concept of an edition; for the VO this is somewhat new because we care about national languages and linking source code.

The latest version of DocRegExt can be found at:

• http://ivoa.net/documents/DocRegExt/

Minor changes in response to RFC comments will be reflected in the build at https://docs.g-vo.org/DocRegExt.pdf; reviewers may want to look at this copy.

You can also use the github repo for commenting: https://github.com/ivoa-std/DocRegExt

Reference Interoperable Implementations

There are existing DocRegExt records from multiple authorities. Try

select ivoid from rr.resource
where res_type='doc:document'

on a RegTAP service (this gives 45 records at this time). See, for instance, https://dc.g-vo.org/I/ivo%3A//edu.euro-vo.org/tutorials/08_m1_distance as an example for a multi-language document, or https://dc.g-vo.org/I/ivo%3A//org.gavo.dc/tutreg/gavo_pyvocourse/rec for a record with links to a source control system.

On the consumer side, there is the register of VO Text Treasures https://dc.g-vo.org/VOTT.

See also http://svn.ari.uni-heidelberg.de/svn/gavo/hdinputs/vott/res/to-dalia-if.py (make sure your browser does not change that to https or you will be asked for credentials); this is a pyVO script that turns DocRegExt metadata as ingested into the Registry into the schema of the cross-discipline search engine at https://dalia.education. This is in active use for feeding them our material.

Implementations Validators

There is a schema file; use any schema validator on instance documents. There is no further, “semantic” validation so far. I would in particularly like to flag everything that has only one sentence in its description as in need of more love, but as the details of such an endeavour are tricky, I doubt that it will ever happen.

Comments from the IVOA Community during RFC/TCG review period: Nov 15,2025 – Jan 15, 2026

The comments from the TCG members during the RFC/TCG review should be included in the next section.

In order to add a comment to the document, please edit this page and add your comment to the list below in the format used for the example (include your Wiki Name so that authors can contact you for further information). When the author(s) of the document have considered the comment, they will provide a response after the comment.

Additional discussion about any of the comments or responses can be conducted on the WG mailing list. However, please be sure to enter your initial comments here for full consideration in any future revisions of this document

• Sample comment by WikiName
  • Response (by WikiName)

Comments from TCG member during the RFC/TCG Review Period: Nov 15. 2025 – Jan 15, 2026

WG chairs or vice chairs must read the Document, provide comments if any (including on topics not directly linked to the Group matters) or indicate that they have no comment.

IG chairs or vice chairs are also encouraged to do the same, althought their inputs are not compulsory.

TCG Chair & Vice Chair

Applications Working Group

There are no major concerns as far as Apps WG goes. The document is understandable in use and purpose. Typos suggestions have been submitted in a separate PR.

• Merged, thanks! -- MarkusDemleitner - 2026-01-26

Following there are few minor comments:

- have you considered EduRegExt as the name?

• VOTT, for instance, has several sort modes, and I think the "currency" of a piece of documentation is just one of many criteria to assess its relevance to a given situation. So, while I generally like implementation advice of this sort (and usually get talked out of it by Mark T.), I think here it would not help implementors much -- MarkusDemleitner - 2026-01-26

- should multiple major versions of document in a language be accepted? Or that is just a consequence of the lack of a mechanism to prevent that.

• A single publisher should only put out a single version of a document at any one time; it's bad enough that we cannot keep the various translations in sync. If a different publisher really thinks a previous version should be preserved for whatever reason, they can add a second resource record. But I'd try to talk them out of it -- MarkusDemleitner - 2026-01-26

Data Access Layer Working Group

Data Model Working Group

Distributed Services & Protocols Working Group

Registry Working Group

Semantics Working Group

Data Curation & Preservation Interest Group

DCP feedbacks.

• listing tools is cool, but as free text, they sound as keywords :(
  This distorts the meaning of linked data in terms of "relationships".
  
  Suggest: (I like the idea to attach tools) it would need an additional step consisting to register tools in registry. A tool-resource with URLs to dowload softwares, documentation(s), examples... it would be nice ?
  
  
  • Absolutely. I've been advocating this sort of thing for a long time, but considerations of registering software have always led to unproductive discussions. Hence, I'd rather not build upon it here. What I could imagine is to reommend ascl identifiers as relatedResource's clear text. Or should we say "put ascl.net/nnnn.mmm into altIdentifier"? -- MarkusDemleitner - 2026-01-26

• Adding type to Documents & tutorials (metadata existing in DCAT or DataCite)
  
  Suggest: add the format of the resource: application/pdf, text/html (WEB service), application/x-ipynb+json (notebook)
  
  For instance, adding formats (such as DataCite) or adding a new interface type (like WebBrower) (eg: xsi:type="vr:WebDocument" and "vr:resultType")
  Example: <interface xsi:type="vr:WebDocument"><resultType>application/x-ipynb+json</resultType></interface>
  • Hm... This isn't resource-level metadata, because it's conceivable that one language comes in in Open Document and another language comes in PDF. And then it's likely that we'll see compound material: PDF plus python source code, say, or perhaps a longer narrative in a PDF and an accompanying notebook. In short: I'd need a good case where having this information would actually influence the discovery process. Until then, I'd tend to believe that if someone really wants to see some content, they won't care too much what format it's in. -- MarkusDemleitner - 2026-01-26

Other feedbacks

• Documents and Resources linking
  The Recommendation allows to create a "Document" with metadata that lists the resources used (we have in CDS this type of resources in different format).
  The recommendation doesn't provide a "reverse" way to add documentation on existing published resource (we have in VizieR). This Document could have an ivoid or an external URL.
  
  eg: The resource ivo://cds.vizier/J/AJ/161/36 has a notebook which is available in the landing page:
  https://cdsarc.cds.unistra.fr/vizier/notebook.gml?source=J/AJ/161/36
  
  Suggest: adding relation IsDocumentedBy (from DataCite) or usedInDocument (invented?)
  an alternative would consist to use interface (enables to specify format with "vr:resultType")

• • I wonder whether IsSupplementedBy isn't what this is about. See p. 6, where we say that tutorials "specifically introducing one or more services should define IsSupplementTo relationships". I think this is the situation that you describe here, and then we'd have this natural inversion. Should we stress this point a bit more? -- MarkusDemleitner - 2026-01-26

Education Interest Group

High Energy Interest Group

Knowledge Discovery Interest Group

Operations Interest Group

Radio Astronomy Interest Group

Solar System Interest Group

Time Domain Interest Group

Standards and Processes Committee

TCG Vote : Jan 1, 2026 – Jan 15, 2026

If you have minor comments (typos) on the last version of the document please indicate it in the Comments column of the table and post them in the TCG comments section above with the date.

<!--
* Set ALLOWTOPICRENAME = TWikiAdminGroup
-->

DocRegExt Proposed Recommendation: Request for Comments

DocRegExt is a VOResource extension for registering documents useful for teaching and learning the Virtual Observatory. It re-uses common VODataService (CatalogResource) metadata and adds the concept of an edition; for the VO this is somewhat new because we care about national languages and linking source code.

The latest version of DocRegExt can be found at:

• http://ivoa.net/documents/DocRegExt/

Minor changes in response to RFC comments will be reflected in the build at https://docs.g-vo.org/DocRegExt.pdf; reviewers may want to look at this copy.

You can also use the github repo for commenting: https://github.com/ivoa-std/DocRegExt

Reference Interoperable Implementations

There are existing DocRegExt records from multiple authorities. Try

select ivoid from rr.resource
where res_type='doc:document'

on a RegTAP service (this gives 45 records at this time). See, for instance, https://dc.g-vo.org/I/ivo%3A//edu.euro-vo.org/tutorials/08_m1_distance as an example for a multi-language document, or https://dc.g-vo.org/I/ivo%3A//org.gavo.dc/tutreg/gavo_pyvocourse/rec for a record with links to a source control system.

On the consumer side, there is the register of VO Text Treasures https://dc.g-vo.org/VOTT.

See also http://svn.ari.uni-heidelberg.de/svn/gavo/hdinputs/vott/res/to-dalia-if.py (make sure your browser does not change that to https or you will be asked for credentials); this is a pyVO script that turns DocRegExt metadata as ingested into the Registry into the schema of the cross-discipline search engine at https://dalia.education. This is in active use for feeding them our material.

Implementations Validators

There is a schema file; use any schema validator on instance documents. There is no further, “semantic” validation so far. I would in particularly like to flag everything that has only one sentence in its description as in need of more love, but as the details of such an endeavour are tricky, I doubt that it will ever happen.

Comments from the IVOA Community during RFC/TCG review period: Nov 15,2025 – Jan 15, 2026

The comments from the TCG members during the RFC/TCG review should be included in the next section.

In order to add a comment to the document, please edit this page and add your comment to the list below in the format used for the example (include your Wiki Name so that authors can contact you for further information). When the author(s) of the document have considered the comment, they will provide a response after the comment.

Additional discussion about any of the comments or responses can be conducted on the WG mailing list. However, please be sure to enter your initial comments here for full consideration in any future revisions of this document

• Sample comment by WikiName
  • Response (by WikiName)

Comments from TCG member during the RFC/TCG Review Period: Nov 15. 2025 – Jan 15, 2026

WG chairs or vice chairs must read the Document, provide comments if any (including on topics not directly linked to the Group matters) or indicate that they have no comment.

IG chairs or vice chairs are also encouraged to do the same, althought their inputs are not compulsory.

TCG Chair & Vice Chair

Applications Working Group

Data Access Layer Working Group

Data Model Working Group

Distributed Services & Protocols Working Group

Registry Working Group

Semantics Working Group

Data Curation & Preservation Interest Group

DCP feedbacks.

• listing tools is cool, but as free text, they sound as keywords :(
  This distorts the meaning of linked data in terms of "relationships".
  
  Suggest: (I like the idea to attach tools) it would need an additional step consisting to register tools in registry. A tool-resource with URLs to dowload softwares, documentation(s), examples... it would be nice ?
  
  

• Adding type to Documents & tutorials (metadata existing in DCAT or DataCite)
  
  Suggest: add the format of the resource: application/pdf, text/html (WEB service), application/x-ipynb+json (notebook)
  
  For instance, adding formats (such as DataCite) or adding a new interface type (like WebBrower) (eg: xsi:type="vr:WebDocument" and "vr:resultType")
  Example: <interface xsi:type="vr:WebDocument"><resultType>application/x-ipynb+json</resultType></interface>

• Documents and Resources linking
  The Recommendation allows to create a "Document" with metadata that lists the resources used (we have in CDS this type of resources in different format).
  The recommendation doesn't provide a "reverse" way to add documentation on existing published resource (we have in VizieR). This Document could have an ivoid or an external URL.
  
  eg: The resource ivo://cds.vizier/J/AJ/161/36 has a notebook which is available in the landing page:
  https://cdsarc.cds.unistra.fr/vizier/notebook.gml?source=J/AJ/161/36
  
  Suggest: adding relation IsDocumentedBy (from DataCite) or usedInDocument (invented?)
  an alternative would consist to use interface (enables to specify format with "vr:resultType")

Education Interest Group

High Energy Interest Group

Knowledge Discovery Interest Group

Operations Interest Group

Radio Astronomy Interest Group

Solar System Interest Group

Time Domain Interest Group

Standards and Processes Committee

TCG Vote : Jan 1, 2026 – Jan 15, 2026

If you have minor comments (typos) on the last version of the document please indicate it in the Comments column of the table and post them in the TCG comments section above with the date.

<!--
* Set ALLOWTOPICRENAME = TWikiAdminGroup
-->

DocRegExt Proposed Recommendation: Request for Comments

DocRegExt is a VOResource extension for registering documents useful for teaching and learning the Virtual Observatory. It re-uses common VODataService (CatalogResource) metadata and adds the concept of an edition; for the VO this is somewhat new because we care about national languages and linking source code.

The latest version of DocRegExt can be found at:

• http://ivoa.net/documents/DocRegExt/

Minor changes in response to RFC comments will be reflected in the build at https://docs.g-vo.org/DocRegExt.pdf; reviewers may want to look at this copy.

You can also use the github repo for commenting: https://github.com/ivoa-std/DocRegExt

Reference Interoperable Implementations

There are existing DocRegExt records from multiple authorities. Try

select ivoid from rr.resource
where res_type='doc:document'

on a RegTAP service (this gives 45 records at this time). See, for instance, https://dc.g-vo.org/I/ivo%3A//edu.euro-vo.org/tutorials/08_m1_distance as an example for a multi-language document, or https://dc.g-vo.org/I/ivo%3A//org.gavo.dc/tutreg/gavo_pyvocourse/rec for a record with links to a source control system.

On the consumer side, there is the register of VO Text Treasures https://dc.g-vo.org/VOTT.

See also http://svn.ari.uni-heidelberg.de/svn/gavo/hdinputs/vott/res/to-dalia-if.py (make sure your browser does not change that to https or you will be asked for credentials); this is a pyVO script that turns DocRegExt metadata as ingested into the Registry into the schema of the cross-discipline search engine at https://dalia.education. This is in active use for feeding them our material.

Implementations Validators

There is a schema file; use any schema validator on instance documents. There is no further, “semantic” validation so far. I would in particularly like to flag everything that has only one sentence in its description as in need of more love, but as the details of such an endeavour are tricky, I doubt that it will ever happen.

Comments from the IVOA Community during RFC/TCG review period: Nov 15,2025 – Jan 15, 2026

The comments from the TCG members during the RFC/TCG review should be included in the next section.

In order to add a comment to the document, please edit this page and add your comment to the list below in the format used for the example (include your Wiki Name so that authors can contact you for further information). When the author(s) of the document have considered the comment, they will provide a response after the comment.

Additional discussion about any of the comments or responses can be conducted on the WG mailing list. However, please be sure to enter your initial comments here for full consideration in any future revisions of this document

• Sample comment by WikiName
  • Response (by WikiName)

Comments from TCG member during the RFC/TCG Review Period: Nov 15. 2025 – Jan 15, 2026

WG chairs or vice chairs must read the Document, provide comments if any (including on topics not directly linked to the Group matters) or indicate that they have no comment.

IG chairs or vice chairs are also encouraged to do the same, althought their inputs are not compulsory.

TCG Chair & Vice Chair

Applications Working Group

Data Access Layer Working Group

Data Model Working Group

Distributed Services & Protocols Working Group

Registry Working Group

Semantics Working Group

Data Curation & Preservation Interest Group

DCP feedbacks.

• listing tools is cool, but as free text, they sound as keywords :(
  This distorts the meaning of linked data in terms of "relationships".
  
  Suggest: (I like the idea to attach tools) it would need an additional step consisting to register tools in registry. A tool-resource with URLs to dowload softwares, documentation(s), examples... it would be nice ?
  
  
• Adding type to Documents & tutorials (metadata existing in DCAT or DataCite)
  
  Suggest: add the format of the resource: application/pdf, text/html (WEB service), application/x-ipynb+json (notebook)
  
  For instance, adding formats (such as DataCite) or adding a new interface type (like WebBrower) (eg: xsi:type="vr:WebDocument" and "vr:resultType")
  Example: <interface xsi:type="vr:WebDocument"><resultType>application/x-ipynb+json</resultType></interface>

Education Interest Group

High Energy Interest Group

Knowledge Discovery Interest Group

Operations Interest Group

Radio Astronomy Interest Group

Solar System Interest Group

Time Domain Interest Group

Standards and Processes Committee

TCG Vote : Jan 1, 2026 – Jan 15, 2026

If you have minor comments (typos) on the last version of the document please indicate it in the Comments column of the table and post them in the TCG comments section above with the date.

<!--
* Set ALLOWTOPICRENAME = TWikiAdminGroup
-->

DocRegExt Proposed Recommendation: Request for Comments

Reference Interoperable Implementations

select ivoid from rr.resource
where res_type='doc:document'

Implementations Validators

Comments from the IVOA Community during RFC/TCG review period: Nov 15,2025 – Jan 15, 2026

The comments from the TCG members during the RFC/TCG review should be included in the next section.

In order to add a comment to the document, please edit this page and add your comment to the list below in the format used for the example (include your Wiki Name so that authors can contact you for further information). When the author(s) of the document have considered the comment, they will provide a response after the comment.

Additional discussion about any of the comments or responses can be conducted on the WG mailing list. However, please be sure to enter your initial comments here for full consideration in any future revisions of this document

• Sample comment by WikiName
  • Response (by WikiName)

Comments from TCG member during the RFC/TCG Review Period: Nov 15. 2025 – Jan 15, 2026

WG chairs or vice chairs must read the Document, provide comments if any (including on topics not directly linked to the Group matters) or indicate that they have no comment.

IG chairs or vice chairs are also encouraged to do the same, althought their inputs are not compulsory.

TCG Chair & Vice Chair

Applications Working Group

Data Access Layer Working Group

Data Model Working Group

Distributed Services & Protocols Working Group

Registry Working Group

Semantics Working Group

Data Curation & Preservation Interest Group

Education Interest Group

High Energy Interest Group

Knowledge Discovery Interest Group

Operations Interest Group

Radio Astronomy Interest Group

Solar System Interest Group

Time Domain Interest Group

Standards and Processes Committee

DocRegExt Proposed Recommendation: Request for Comments

DocRegExt is a VOResource extension for registering documents useful for teaching and learning the Virtual Observatory. It re-uses common VODataService (CatalogResource) metadata and adds the concept of an edition; for the VO this is somewhat new because we care about national languages and linking source code.

• http://ivoa.net/documents/DocRegExt/

Minor changes in response to RFC comments will be reflected in the build at https://docs.g-vo.org/DocRegExt.pdf; reviewers may want to look at this copy.

Reference Interoperable Implementations

There are existing DocRegExt records from multiple authorities. Try

select ivoid from rr.resource
where res_type='doc:document'

on a RegTAP service (this gives 45 records at this time). See, for instance, https://dc.g-vo.org/I/ivo%3A//edu.euro-vo.org/tutorials/08_m1_distance as an example for a multi-language document, or https://dc.g-vo.org/I/ivo%3A//org.gavo.dc/tutreg/gavo_pyvocourse/rec for a record with links to a source control system.

On the consumer side, there is the register of VO Text Treasures https://dc.g-vo.org/VOTT.

See also http://svn.ari.uni-heidelberg.de/svn/gavo/hdinputs/vott/res/to-dalia-if.py (make sure your browser does not change that to https or you will be asked for credentials); this is a pyVO script that turns DocRegExt metadata as ingested into the Registry into the schema of the cross-discipline search engine at https://dalia.education. This is in active use for feeding them our material.

Implementations Validators

There is a schema file; use any schema validator on instance documents. There is no further, “semantic” validation so far. I would in particularly like to flag everything that has only one sentence in its description as in need of more love, but as the details of such an endeavour are tricky, I doubt that it will ever happen.

Comments from the IVOA Community during RFC/TCG review period: Nov 15,2025 – Jan 15, 2026

The comments from the TCG members during the RFC/TCG review should be included in the next section.

In order to add a comment to the document, please edit this page and add your comment to the list below in the format used for the example (include your Wiki Name so that authors can contact you for further information). When the author(s) of the document have considered the comment, they will provide a response after the comment.

Additional discussion about any of the comments or responses can be conducted on the WG mailing list. However, please be sure to enter your initial comments here for full consideration in any future revisions of this document

• Sample comment by WikiName
  • Response (by WikiName)

Comments from TCG member during the RFC/TCG Review Period: Nov 15. 2025 – Jan 15, 2026

WG chairs or vice chairs must read the Document, provide comments if any (including on topics not directly linked to the Group matters) or indicate that they have no comment.

IG chairs or vice chairs are also encouraged to do the same, althought their inputs are not compulsory.

TCG Chair & Vice Chair

Applications Working Group

Data Access Layer Working Group

Data Model Working Group

Distributed Services & Protocols Working Group

Registry Working Group

Semantics Working Group

Data Curation & Preservation Interest Group

Education Interest Group

High Energy Interest Group

Knowledge Discovery Interest Group

Operations Interest Group

Radio Astronomy Interest Group

Solar System Interest Group

Time Domain Interest Group

Standards and Processes Committee

TCG Vote : Jan 1, 2026 – Jan 15, 2026

If you have minor comments (typos) on the last version of the document please indicate it in the Comments column of the table and post them in the TCG comments section above with the date.

<-- 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
-->

DocRegExt Proposed Recommendation: Request for Comments

DocRegExt is a VOResource extension for registering documents useful for teaching and learning the Virtual Observatory. It re-uses common VODataService (CatalogResource) metadata and adds the concept of an edition; for the VO this is somewhat new because we care about national languages and linking source code.

Latest version of DocRegExt can be found at:

• http://ivoa.net/documents/DocRegExt/

Minor changes in response to RFC comments will be reflected in the build at https://docs.g-vo.org/DocRegExt.pdf; reviewers may want to look at this copy.

Reference Interoperable Implementations

There are existing DocRegExt records from multiple authorities. Try

select ivoid from rr.resource
where res_type='doc:document'

on a RegTAP service (this gives 45 records at this time). See, for instance, https://dc.g-vo.org/I/ivo%3A//edu.euro-vo.org/tutorials/08_m1_distance as an example for a multi-language document, or https://dc.g-vo.org/I/ivo%3A//org.gavo.dc/tutreg/gavo_pyvocourse/rec for a record with links to a source control system.

On the consumer side, there is the register of VO Text Treasures https://dc.g-vo.org/VOTT.

See also http://svn.ari.uni-heidelberg.de/svn/gavo/hdinputs/vott/res/to-dalia-if.py (make sure your browser does not change that to https or you will be asked for credentials); this is a pyVO script that turns DocRegExt metadata as ingested into the Registry into the schema of the cross-discipline search engine at https://dalia.education. This is in active use for feeding them our material.

Implementations Validators

There is a schema file; use any schema validator on instance documents. There is no further, “semantic” validation so far. I would in particularly like to flag everything that has only one sentence in its description as in need of more love, but as the details of such an endeavour are tricky, I doubt that it will ever happen.

Comments from the IVOA Community during RFC/TCG review period: Nov 15,2025 – Jan 15, 2026

The comments from the TCG members during the RFC/TCG review should be included in the next section.

In order to add a comment to the document, please edit this page and add your comment to the list below in the format used for the example (include your Wiki Name so that authors can contact you for further information). When the author(s) of the document have considered the comment, they will provide a response after the comment.

Additional discussion about any of the comments or responses can be conducted on the WG mailing list. However, please be sure to enter your initial comments here for full consideration in any future revisions of this document

• Sample comment by WikiName
  • Response (by WikiName)

Comments from TCG member during the RFC/TCG Review Period: Nov 15. 2025 – Jan 15, 2026

WG chairs or vice chairs must read the Document, provide comments if any (including on topics not directly linked to the Group matters) or indicate that they have no comment.

IG chairs or vice chairs are also encouraged to do the same, althought their inputs are not compulsory.

TCG Chair & Vice Chair

Applications Working Group

Data Access Layer Working Group

Data Model Working Group

Distributed Services & Protocols Working Group

Registry Working Group

Semantics Working Group

Data Curation & Preservation Interest Group

Education Interest Group

High Energy Interest Group

Knowledge Discovery Interest Group

Operations Interest Group

Radio Astronomy Interest Group

Solar System Interest Group

Time Domain Interest Group

Standards and Processes Committee

TCG Vote : Jan 1, 2026 – Jan 15, 2026

If you have minor comments (typos) on the last version of the document please indicate it in the Comments column of the table and post them in the TCG comments section above with the date.

<-- 

 Set ALLOWTOPICRENAME = TWikiAdminGroup
 
-->