From 026f73e879e07b2f3c580914ffdfa18ae241cfd7 Mon Sep 17 00:00:00 2001
From: "Dong H. Ahn" <ahn1@llnl.gov>
Date: Sat, 6 Jun 2020 11:38:23 -0700
Subject: [PATCH] rfc20: add optional "attributes" top-level key

Problem: there is currently no way for a scheduler
to emit opaque information specific to the scheduler itself.
For example, as part of resource restruction work within Fluxion,
a need arose to emit the queue name into RV1 so that
when a multi-queue-capable Fluxion module is reloaded,
each currently running job can be enqueued into
the corresponding queue.

Introduce the "attributes" at the top level which
can have the "system" key to contain system
specific information pertaining to the
creation of this R document.
W/ this change, Fluxion can now stick the queue name
to "attributes.system.scheduler" and fetch this
back to reconstruct its reconstruction correctly.
---
 spec_20.rst | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/spec_20.rst b/spec_20.rst
index ff3ad185..1f0555c8 100644
--- a/spec_20.rst
+++ b/spec_20.rst
@@ -99,13 +99,17 @@ Resource Set Format Definition
 
 The JSON documents that conform to the *R* format SHALL be referred
 to as *R* JSON documents or in short *R* documents.
-An *R* JSON document SHALL consist of a dictionary with three
-keys: ``version``, ``execution`` and ``scheduling``. It SHALL be valid if and only
+An *R* JSON document SHALL consist of a dictionary with four
+keys: ``version``, ``execution``, ``scheduling`` and ``attributes``.
+It SHALL be valid if and only
 if it contains the ``version`` key and either or both the ``execution``
 and ``scheduling`` keys. The value of the ``execution`` key SHALL contain
 sufficient data for the execution system to perform its
 core tasks. The value of ``scheduling`` SHALL contain sufficient data
-for schedulers.
+for schedulers. Finally, the value of ``attributes`` SHALL provide
+optional information including but not being limited
+to data specific to the scheduler used to create
+this JSON document.
 
 
 Version
@@ -239,6 +243,29 @@ as described in RFC 4. It SHALL contain two keys:
    above. (e.g., "contains" relationship within the "containment" subsystem).
 
 
+Attributes
+~~~~~~~~~~
+The purpose of the ``attributes`` key is to provide optional
+information on this *R* document. The ``attributes`` key SHALL
+be a dictionary of one key: ``system``.
+Other keys are reserved for future extensions.
+
+**system**
+Attributes in the ``system`` dictionary provide additional system
+information that have affected the creation of this *R* document.
+All of the system attributes are optional.
+
+A common system attribute is:
+
+**scheduler**
+The value of the ``scheduler`` is a free-from dictionary that
+may provide the information specific to the scheduler used
+to produce this document. For example, a scheduler that
+manages multiple job queues may add ``queue=batch``
+to indicate that this resource set was allocated from within
+its ``batch`` queue. 
+
+
 References
 ----------