update documentation

docs/source/for-developers/add-new-schema.md

@@ -33,16 +33,21 @@ releases them.
 
 Case 3: You want to include schema definition files with the ``pittgoogle-client`` package. Follow
 ``elasticc`` as an example. (1) Commit the files to the repo under the *pittgoogle/schemas* directory. It
-is recommended that the main file name follow the syntax "\<schema_name\>.avsc". (2) Point the ``path``
-field at the new file, relative to the repo root. (3) If you've followed the recommendations, the default
-``helper`` should work, but you should check (more below). If you need to implement your own helper, do it.
+is recommended that the main filename follow the syntax "<schema_name>.avsc". (2) Point ``path``
+at the main file, relative to the package root. If the Avro schema is split into multiple files, you
+usually only need to point to the main one. (3) If you've followed the recommendations then the default
+``helper`` should work, but you should check (more below). If you need to implement your own helper
+or update the existing, do it.
 
 ## Potentially Required
 
 ### pittgoogle/types_.py
 
 *pittgoogle/types_.py* is the file containing the :class:`pittgoogle.types_.Schema` class.
 
+If ``schemaless_alert_bytes='false'``, the defaults (mostly null/None) should work and you can ignore
+this file (skip to the next section).
+
 A "helper" method must exist in :class:`pittgoogle.types_.Schema` that can find and load your new schema
 definition. The ``helper`` field in the yaml manifest (above) must be set to the name of this method. If a
 suitable helper method does not already already exist for your schema, add one to this file by following

pittgoogle/registry_manifests/schemas.yml

@@ -1,11 +1,6 @@
-# Guidelines:
-# - Schema names must start with the name of the survey. If the survey has more than one schema
-#   the survey name should be followed by a "." and then a schema-specific specifier(s).
-# - If a schema file is also being registered (path key), it is recommended that the file have the
-#   same name (path stem) as the schema. Avro is the only file type currently implemented, and the file name
-#   must end with ".avsc".
-# - The path must be relative to the package directory or null if no schema file is being registered.
-#
+# Add an entry to this yaml file to register a new schema.
+# A template is given below for convenience.
+# See docs/source/for-developers/add-new-schema.md for more information.
 #
 # # TEMPLATE
 # - name: ''

pittgoogle/schemas/maps/TEMPLATE.yml

@@ -10,19 +10,29 @@ alertid: alertId  # str or int (typical type for the value of the field that bot
 objectid: [diaObject, diaObjectId]  # str or int
 sourceid: [diaSource, diaSourceId]  # str or int
 #
+# Sources and Objects
+source: diaSource  # record
+object: diaObject  # record
+prv_forced_sources: prvDiaForcedSources  # array of records
+prv_sources: prvDiaSources  # array of records
+ss_object: ssObject  # record
+#
 # Everything else.
+# [TODO] Currently can only use each key/value pair to get data from one place, but the same field
+# often exists in multiple places (e.g., source and prv_sources both have mjd data).
+# How to make this more flexible and use it to access both/all data with a given name?
 cutout_difference: cutoutDifference  # bytes (image stamp)
 cutout_science: cutoutScience  # bytes (image stamp)
 cutout_template: cutoutTemplate  # bytes (image stamp)
-dec: decl  # float
-filter: filterName  # int (`Schema.filter_map` often maps this to the filter's common name, like 2 -> 'r')
-flux: psFlux  # float (typically PSF flux, not aperture)
-fluxerr: psFluxErr  # float
-mag: magpsf  # float (typically PSF mag, not aperture)
-magerr: sigmapsf  # float
-magzp: magzpsci  # float (magnitude zero point)
-mjd: midPointTai  # float
-prv_forced_sources: prvDiaForcedSources  # record or array
-prv_sources: prvDiaSources  # record or array
-ra: ra  # float
-source: diaSource  # record or array
+dec: [diaSource, dec]  # float
+dec_err: [diaSource, decErr]  # float
+filter: [diaSource, filterName]  # int (`Schema.filter_map` often maps this to the filter's common name, like 2 -> 'r')
+flux: [diaSource, psFlux]  # float (typically PSF flux, not aperture)
+flux_err: [diaSource, psFluxErr]  # float
+mag: [diaSource, magpsf]  # float (typically PSF mag, not aperture)
+mag_err: [diaSource, sigmapsf]  # float
+mag_zp: [diaSource, magzpsci]  # float (magnitude zero point)
+mjd: [diaSource, midPointTai]  # float
+ra: [diaSource, ra]  # float
+ra_err: [diaSource, raErr]  # float
+snr: [diaSource, snr]  # float