Repository: spacetelescope/rad (language: python)

Issue:
Docs: Clarification that file schema means top-level field's tag schemas
In the docs there's a handful of mentions of "file schema" which are separately listed than the "tags". For those unfamiliar with ASDF, this isn't particularly harmful. For those more familiar with ASDF, it's a bit ambiguous because file schema can also mean a schema to describe the file schema as a whole.

Discussing with @braingram , I come to learn that ...

> the "file schema" headings there refer to the ASDF schema used for the top-level roman object in the file.
> — @braingram

..., therefore all file schemas are actually tag schemas and only validates the fields under `roman` rather than a schema for the entire file. 

```yaml
...
roman: !<asdf://path/to/schemas/schema-x.y.z>
  meta: ...
  data: ...
```

Furthermore, there isn't a true file schema that enforces `roman` must be used as the top level. Perhaps something with this schema...

```yaml
allOf:
  - $ref: http://stsci.edu/schemas/asdf/asdf-schema-1.0.0
  - type: object
    properties:
      roman:
        type: object
    required: [roman]
```








Discussion / hints:

Fix patch:
diff --git a/changes/446.doc.rst b/changes/446.doc.rst
new file mode 100644
index 00000000..47c1acc0
--- /dev/null
+++ b/changes/446.doc.rst
@@ -0,0 +1,1 @@
+Update schema docs to clarify headings and add links to roman_datamodels and asdf.
diff --git a/docs/reference_files.rst b/docs/reference_files.rst
index 18bd42d3..a57ea791 100644
--- a/docs/reference_files.rst
+++ b/docs/reference_files.rst
@@ -3,7 +3,7 @@
 Reference File Schemas
 ======================
 
-Nancy Grace Roman Space Telescope Reference Files:
+Schemas used in Nancy Grace Roman Space Telescope Reference Files:
 
 .. asdf-autoschemas::
     :standard_prefix: schemas/reference_files
diff --git a/docs/schemas.rst b/docs/schemas.rst
index 31128430..577ddb52 100644
--- a/docs/schemas.rst
+++ b/docs/schemas.rst
@@ -3,29 +3,33 @@
 Science Products Schemas
 ========================
 
-Level 1 (uncalibrated) File schema
-----------------------------------
+The following ASDF schemas define the structures used in Nancy Grace Roman Space Telescope files.
+See :ref:doc:`roman_datamodels:roman_datamodels/datamodels/general_structure` for more details about how these schemeas are used.
+See :ref:`asdf-standard:asdf-schemas` for more information about ASDF schemas.
+
+Level 1 (uncalibrated) schema
+-----------------------------
 
 .. asdf-autoschemas::
 
   wfi_science_raw-1.0.0
 
-Level 2 (calibrated exposure) File schema
------------------------------------------
+Level 2 (calibrated exposure) schema
+------------------------------------
 
 .. asdf-autoschemas::
 
    wfi_image-1.0.0
 
-Level 3 (resampled mosaic) File schema
---------------------------------------
+Level 3 (resampled mosaic) schema
+---------------------------------
 
 .. asdf-autoschemas::
 
   wfi_mosaic-1.0.0
 
-Level 4 File schemas
---------------------
+Level 4 (ancillary) schemas
+---------------------------
 
 .. asdf-autoschemas::
 


Test patch:
diff --git a/docs/ground_tests.rst b/docs/ground_tests.rst
index 638ca904..451bdcba 100644
--- a/docs/ground_tests.rst
+++ b/docs/ground_tests.rst
@@ -1,7 +1,7 @@
 .. _ground_tests:
 
-Ground Tests File Schemas
-=========================
+Ground Tests Schemas
+====================
 
 FPS
 ---