bcp-001 amwa specification process · amwa bcp-001 - (c) amwa 2016, cc attribution-sharealike 4.0...
TRANSCRIPT
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 1
_____________________________________________________________________________
BCP-001 AMWA Specification Process
Type: Best Current Practice (BCP) Project leader: Brad Gilmer, AMWA Maturity level: Proposed Specification Date published: June 3, 2016Location: http://amwa.tv/projects/BCP-001.pdf Comment: none
__________________________________________________________________
Document history
Date of action Description Section in current version
Section in prior version
2015-12-02 Baseline draft assembled by Carl Fleischhauer and Brad Gilmer, October and November 2015
baseline
2015-12-07_1 Carl added wording from Brad with more specifics on the initial requirements for projects and the IPR "mode" declaration.
3.1 New add; precedes former 3.1, now renumbered 3.2
2015-12-07_2 Adjustments to appendixes A and B to accommodate Tom Heritage's suggestions about increasing the flexibility of "building on GitHub" and also-publishing via AMWA.
Appendixes A and B
Appendixes A and B
2015-12-20 Numerous changes suggested by Brad, elaborated and executed by Carl. Highlighting (now removed) marks areas of special concern or high uncertainty.
Everywhere, too many to list; Carl kept Brad's marked up copy
Everywhere, too many to list
2016-02-08 Changes typed by Carl, with generalized OK from Brad. These address the "areas of special concern or high uncertainty" from 2015-02-01. The new wording was yellow-highlighted in the 8 February 2016 version as posted on BaseCamp.
3.3.4.1, p 10 5.3.3, p 14 Appendix A, p 15 Appendix B, p 19
same
2016-03-03 Changes to (1) make GitHub references in main document refer to "GitHub or equivalent code repository approved by AMWA board," (2) rewording of appendix B to make it more general: "about code repositories" and not just about GitHub. Indication that appendix B will be supplemented by additional appendixes if additional guidance is needed.
Many micro-adjustments throughout.
same
2016-03-11 Creative Commons license description edited to make the "share-alike" license the one that AMWA uses for specifications.
5.3.3 same
2016-04-11 Numerous changes from Brad and from a Basecamp thread with input from Peter Brightwell, Thomas Heritage, and Phil Tudor.
Many: in this copy, significant changes are highlighted.
--
2016-04-27 Identical text to preceding. NOTE: identification of project leader in header is left in. However, Brad Gilmer has proposed deleting this.
Clean copy, no highlighting
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 2
!"#$%&'(&)'*!%*!+&
,&&! !-%&"./"&+0%)1(1)"!1'*&02')%++3&"*&'4%241%/ 55555555555555555555555555555555555555555555555555556!,5,! 1789:;<=8>:7 55555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555556!,5?! "./"&+@A=>B>=C8>:7&09:=ADD&E:CFD 5555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555556!,5G! "=H7:IFA;JAKA78 55555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555556!
?! 0L#$1)"!1'*&'(&"./"&+0%)1(1)"!1'*+55555555555555555555555555555555555555555555555555555555555555555555555555556!G! "./"&+0%)1(1)"!1'*+3&+%4%*&!M0%+ 55555555555555555555555555555555555555555555555555555555555555555555555555555555556!
G5,! "@@F>=C8>:7&+@A=>B>=C8>:7D&N"+O 55555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555556!G5?! PC8C&.:;AF&+@A=>B>=C8>:7D&N.+O 55555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555556!G5G! 178A9BC=A&+@A=>B>=C8>:7D&N1+O55555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555Q!G56! #AD8&)<99A78&09C=8>=A&N#)0O55555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555Q!G5Q! 17B:9KC8>RA&+@A=>B>=C8>:7D 5555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555Q!G5S! %T@A9>KA78CF&+@A=>B>=C8>:7 555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555Q!G5U! ->D8:9>=CF&+@A=>B>=C8>:7&NB:9&D<@A9DA;A;&>8AKDO 555555555555555555555555555555555555555555555555555555555555555555555555Q!G5V! 17=:9@:9C8>:7&:B&:8WA9&D8C7;C9;D&C7;&D@A=>B>=C8>:7 5555555555555555555555555555555555555555555555555555555555555555Q!"#$#%! &'()*+)*,-.)'!)/!,'!0+1'!2-,'3,*3 #########################################################################################################4!"#$#5! &'()*+)*,-.)'!)/!0-61*!2+1(./.(,-.)'7 ####################################################################################################4!
6! "./"&+0%)1(1)"!1'*+3&$%4%$+&'(&."!L21!M55555555555555555555555555555555555555555555555555555555555555555S!65,! 09A9AX<>D>8A3&+@A=>B>=C8>:7D&.<D8&#A&PARAF:@A;&/>8W>7&C7&"@@9:RA;&09:YA=8555555555555555S!8#%#%! 9*):1(-!;<-6)*.=,-.)'#####################################################################################################################################>!
65?! (>9D8&.C8<9>8Z&$ARAF3&/:9H&>7&09:J9ADD&N/10O5555555555555555555555555555555555555555555555555555555555555555555555555555U!8#5#%! ;?)<-!@)*A7!.'!9*)B*177##############################################################################################################################C!8#5#5! 9*1*1D<.7.-17!/)*!@&97###################################################################################################################################C!8#5#"! EF1G,-.)'!-)!H1I-!J,-<*.-K!L1G1FM!/*)N!@&9!-)!9*)+)713!;J@;!2+1(./.(,-.)' ##################$!
65G! +A=:7;&.C8<9>8Z&$ARAF3&09:@:DA;&"./"&+@A=>B>=C8>:7D 55555555555555555555555555555555555555555555555555555555[!8#"#%! ;?)<-!9*)+)713!;J@;!2+1(./.(,-.)'7###################################################################################################O!8#"#5! &'/)*N,-.G1!,'3!EI+1*.N1'-,F!2+1(./.(,-.)'7 #####################################################################################O!8#"#"! 9*1*1D<.7.-17!/)*!9*)+)713!;J@;!2+1(./.(,-.)'7 ############################################################################O!8#"#8! EF1G,-.)'!-)!-61!H1I-!J,-<*.-K!L1G1FM!/*)N!9*)+)713!-)!;J@;!2+1(./.(,-.)' ################# %P!
656! !W>9;&.C8<9>8Z&$ARAF3&"./"&+@A=>B>=C8>:7D 5555555555555555555555555555555555555555555555555555555555555555555555555555 ,,!8#8#%! ;?)<-!;J@;!2+1(./.(,-.)'7 #################################################################################################################### %%!8#8#5! 9*1*1D<.7.-17!/)*!;J@;!2+1(./.(,-.)'7M############################################################################################# %%!
65Q! 2AR>D>7J&C7&"./"&+@A=>B>=C8>:755555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555 ,?!65S! 2A8>9>7J&C7&"./"&+@A=>B>=C8>:7 55555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555 ,?!
Q&&)'*($1)!&2%+'$L!1'*&"*P&"00%"$+5555555555555555555555555555555555555555555555555555555555555555555555555555555555,?!Q5,! P>D@<8AD&/>8W>7&C&/:9H>7J&E9:<@55555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555 ,?!Q5?! "@@ACF&8:&8WA&"./"&#:C9;555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555 ,G!Q5G! "@@ACFD&09:=A;<9A5555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555 ,G!
S! 1*!%$$%)!L"$&02'0%2!M555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555555,G!S5,! 1789:;<=8:9Z&*:8A&:7&"./"&0<\F>=C8>:7&C7;&102&0:F>=Z 5555555555555555555555555555555555555555555555555555 ,G!S5?! ):@Z9>JW8&C7;&$>=A7D>7J&:B&"./"&+@A=>B>=C8>:7D 555555555555555555555555555555555555555555555555555555555555555555 ,6!>#5#%! Q.771N.',-.)'!)/!7+1(./.(,-.)'7!,-!')!()7-######################################################################################### %8!>#5#5! 2+1(./.(,-.)'7!(,**K!;J@;!()+K*.B6-!')-.(1 ################################################################################### %8!>#5#"! 2+1(./.(,-.)'7!(,**K!R*1,-.G1!R)NN)'7!RR!STU2;!F.(1'71 ######################################################### %8!>#"#8! 2+1(./.(,-.)'7!.'!-61!/)*N!)/!7)/-V,*1!(,**K!-61!;+,(61!5#P!F.(1'71###################################### %8!
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 3
"@@A7;>T&"5&&17=F<D>:7&:B&1;A78>B>A9D]&!>8FAD]&C7;&2ABA9A7=AD 555555555555555555555555555555555555555555555,Q!"5,! "./"&D@A=>B>=C8>:7&9AFC8>:7DW>@D&8:&:8WA9&;:=<KA78D&:9&;C8C 555555555555555555555555555555555555555 ,Q!;#5! ;J@;!.31'-./.1*W!-.-F1W!,'3!)-61*!3,-,!.'!7+1(./.(,-.)'!61,31*#################################################### %4!;#5#%! &FF<7-*,-.G1!1I,N+F1!)/!,!61,31* ############################################################################################################ %4!
"5G! '8WA9&:9JC7>^C8>:7&>;A78>B>A9&C7;&8>8FA&>7&D@A=>B>=C8>:7&D=:@A&D8C8AKA785555555555555555555555 ,S!;#"#%! &FF<7-*,-.G1!1I,N+F1!)/!)-61*!)*B,'.=,-.)'!.'/)*N,-.)'!.'!7()+1!7-,-1N1'-###################### %>!
"56! 2ABA9A7=AD&8:&E>8-<\&:9&:8WA9&=:;A&9A@:D>8:9Z&IWA9A&9AFARC78555555555555555555555555555555555555555 ,S!;#8#%! X1/1*1'(1!-)!-61!)G1*,FF!+*):1(-!.'!Y.-Z<?!)*!)-61*!*1+)7.-)*K############################################### %>!;#8#5! &FF<7-*,-.G1!1I,N+F17!)/!)G1*,FF!Y.-Z<?!+*):1(-!*1/1*1'(1 ######################################################### %>!;#8#"! X1/1*1'(1!-)!+*):1(-!71BN1'-7!)*
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 4
1 THE AMWA SPECIFICATION PROCESS: AN OVERVIEW
1.1 Introduction This document describes the process by which specifications are introduced and established by the Advanced Media Workflow Association (AMWA). As is explained in section 3, in the AMWA context, the term specification covers a range of entities such as prose documents, machine-readable documents in markup language, applications or software.
In simplified outline, the process of creating an AMWA Specification is straightforward: 1) a specification undergoes a period of development and several iterations of review by the community, usually in a working group; 2) the specification is revised as necessary, based upon experience and published as a Proposed Specification; and 3) the work may ultimately be published as a formal Specification by the AMWA Board, acting on behalf of AMWA's membership.
1.2 AMWA Specification Process Goals The goals of the AMWA Specification process are:
• Interoperability • Satisfying business needs • Technical robustness • Reusability and composability • Timeliness
1.3 Acknowledgement The AMWA process is inspired by the work of the Internet Engineering Task Force (IETF) and the AMWA gratefully acknowledges their influence.
2 PUBLICATION OF AMWA SPECIFICATIONS
AMWA specifications of all types are published according to methods established by the AMWA Board of Directors. As of the date of approval of this process document, the authoritative version of any given AMWA specification is found on the AMWA website (http://www.amwa.tv).
3 AMWA SPECIFICATIONS: SEVEN TYPES
Every AMWA specification must be identified as one of the types of specifications listed in this section.
3.1 Application Specifications (AS) Applications Specifications define a set of rules that constrain a pre-existing standard—like MXF—to suit a specific application. Each has been created to satisfy the clearly defined business need of a member organization.
3.2 Data Model Specifications (MS) Data Model Specifications represent a model or mapping in any sense e.g. data model, system architecture, or storage mapping.
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 5
3.3 Interface Specifications (IS) Interface specifications, typically expressed as APIs, support the interoperation of equipment and applications.
3.4 Best Current Practice (BCP) Best Current Practices are intended to define and ratify the community's best current thinking on statements of principle or the best ways to perform certain operations or process functions.
3.5 Informative Specifications Informative Specifications are published for the general information of the workflow community, and may not represent a community consensus or recommendation. The informative designation is intended to provide for the timely publication of a very broad range of documents from many sources, subject only to editorial considerations and to verification that there has been adequate coordination with the process for AMWA specifications.
Specifications that have been prepared by persons or organizations that are not members of AMWA may be published as Informative Specifications with the permission of the owner and the concurrence of the AMWA Board.
3.6 Experimental Specification Experimental Specifications are typically part of some research or development effort. Such specifications are published to inform the community and may serve as an archival record of the work. Such specifications are subject only to editorial considerations and to verification that there has been adequate coordination with the process for AMWA specifications. An Experimental Specification may be the output of an organized AMWA research effort or it may be an individual contribution.
3.7 Historical Specification (for superseded items) An AMWA Specification that has been superseded by a more recent specification or is for any other reason considered to be obsolete is assigned to the "Historical" level.
3.8 Incorporation of other standards and specification
3.8.1 Incorporation of an Open Standard
An AMWA Specification may incorporate an open external standard by reference. For example, many AMWA Application Specifications incorporate by reference SMPTE and EBU standards.
3.8.2 Incorporation of Other Specifications
Other proprietary specifications may be incorporated by reference to a version of the specification as long as the proprietor meets the IPR requirements outlined in the AMWA IPR Policy (see section 6).
If the proprietary specification is not widely and readily available, the AMWA Board may request that it be published as an AMWA Informative Specification.
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 6
AMWA specifications should not favor one particular proprietary specification over technically equivalent and competing specification(s) by making any incorporated vendor specification "required" or "recommended."
4 AMWA SPECIFICATIONS: LEVELS OF MATURITY
AMWA specifications fall into three levels of maturity: • Work in Progress: initial version(s) for review, feedback, and prototyping • Proposed Specification: specification ready for implementation and product development • Specification: specification proven in use in products and real workflows
AMWA Specifications have normative force not simply because they have been published but rather because they demonstrate their value through a process of review, implementation, and proven use.
Not all specifications will move through the three levels. Some specifications will make their contribution to the community while remaining as Works in Progress or in a Proposed Specification status.
4.1 Prerequisite: Specifications Must Be Developed Within an Approved Project
4.1.1 Project Authorization
The drafting of a specification must be part of an AMWA project that has been approved by the AMWA Board. Work may not start on a project until it is approved.
4.1.1.1 Project Authorization Process
Projects are authorized via a lightweight process in which a project proponent sends an email to the AMWA Executive Director outlining the following: • Name of the project • Business purpose • Deliverables • Other proponents of the project • IPR Mode Declaration (see 3.1.1.3 below) • Description of anticipated resource requirement • Source of resources
Note that, with the exception of board-initiated projects, all AMWA projects must be self-sustaining, meaning that proponents need to bring the resources required in order to complete the project. This can be in the form of contributions of time and effort from proponents, or in the form of cash that may be used by the AMWA to retain personnel who would do the work.
4.1.1.2 Project Owner
The project owner is responsible for facilitating the project. The owner may select others who are part of the project to serve as chairs of committees, document editors, etc., but ultimately, the project owner is responsible for ensuring the project moves forward and that decisions are made in a timely manner. The project owner is also empowered to resolve conflicts should they occur. The project owner may be an organization, but the organization must nominate a single
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 7
individual, whose contact information will be made public, and who has the authority to speak for the project owner.
If a project owner steps down, then the AMWA will attempt to locate another project owner, first among those who are/were involved in the project, and then within the broader AMWA membership. If a project owner cannot be found within six months, then the project will be terminated, and further work on the project under the approved Project Authorization shall not be carried forward.
Note that the project owner does not own the intellectual property resulting from the project or the resulting specification. All output of AMWA activities is copyrighted by the AMWA.
4.1.1.3. Project IPR Mode Declaration
Every project authorization must have an IPR Mode Declaration that states whether contributions to the project may be made on a RAND-Free or RAND basis. See section 6 below and the AMWA IPR FAQ for more information: • Advanced Media Workflow Association IPR Policy: Frequently Asked Questions:
http://www.amwa.tv/about/policies/AMWA_IPR_Policy_FAQ_V3.0.pdf
4.2 First Maturity Level: Work in Progress (WIP)
4.2.1 About Works in Progress
The initial or entry-level maturity for specifications is Work in Progress (WIP). In the usual case, this is a designation used for a working committee document being actively edited. WIPs are visible to AMWA members and to the public, and comments are accepted by the project's sponsors.
Any contributions or substantive technical comments from non-AMWA members to a Work in Progress must be accompanied by an IPR declaration form. IPR declaration forms may be found in the AMWA IPR policy available at http://www.amwa.tv/policies.
WIPs are not assigned an AMWA identifier (type designation and number; see appendix A). Instead the committee is expected to come up with a short descriptive title for the work, with some form of wording or tagging to support version control, when appropriate. Example:
• AMWA WIP. Restful API for MXF Versioning to support AS-02, version 1.2.
The WIP should also contain a note stating the intended document type (i.e., MS, IS, Experimental).
4.2.2 Prerequisites for WIPs
Works in Progress: • Must be part of an approved AMWA project, i.e., a project approved by the AMWA Board. • Must have a declared IPR mode as part of the approved project description (acceptable
options are RAND or RAND-Z).
AMWA specifications must carry specified copyright notices and licenses. See section 6.3 for details.
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 8
Some Works in Progress may be created in GitHub or another code repository approved by AMWA Board. Typically these will include application source code, and/or interface or data definitions that are written in a machine- and human-readable form (e.g. XML, JSON, RAML, RDF). Cross-referencing must be provided for such WIPs: (a) in the AMWA specification, provide the number for the code repository version and appropriate URL information and (b) in the code repository expression of the specification, provide identifying and URL information about the corresponding AMWA specification. See appendix B.
4.2.3 Elevation to Next Maturity Level: from WIP to Proposed AMWA Specification
4.2.3.1 Elevation Actions: Project Proponent
Project proponent notifies the AMWA Operations Manager via written request that a given WIP has met elevation criteria. The written request includes:
• Identification of the item type, i.e., IS, AS, Informative, etc. • Proposed title, generally the same as the WIP title (see above, see also examples) • Written description of how the current WIP version meets the prerequisites for Proposed
AMWA Specifications (or AMWA Informative or Experimental Specifications) outlined in section 4.3.3 below, i.e., the written report responds to the following questions:
o What evidence is there to attest to the item's value to the field? o Are there any known technical issues? o Is the item stable, and what evidence can be offered to that state? o Has the committee addressed and resolved any design choices? o Is the item well understood by its creators, is it written or commented in a way
that supports comprehensibility by others? o What notice and opportunity for review has been provided to the community, and
what sorts of responses have been received? o When applicable, does the committee believe that implementations will be
developed in the future? o Does this specification include application source code, and/or interface or data
definitions that are written in a machine- and human-readable form (e.g. XML, JSON, RAML, RDF), being created in GitHub or other code repository approved by AMWA Board? If so, describe and/or provide URLs or other identifiers for appropriate elements in the code repository. See also appendix B.
4.2.3.2 Elevation Actions: AMWA Operations Manager
The AMWA Operations Manager: • Assigns the AMWA identifier, confirms the title, and ensures that other document-header
elements are established, following the patterns presented in appendix A. For example: o IS-02 (Proposed). Restful API for MXF Versioning to support AS-02, version 1.2
• Issues Last Call (two-week notice) to AMWA members. • Ensures that IPR process has been followed • Supports the board in selecting an editor to review the specification on behalf of the AMWA,
and monitors the editor's progress in this task • Notifies Board that they may object to elevation of the work from WIP to Proposed
Specification, but being unresponsive to the Last Call is understood as a vote to allow elevation to proceed.
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 9
4.2.3.3 Elevation Actions: AMWA Board
The AMWA Board: • may optionally review materials from the proponent and the AMWA Operations
Manager (recommended practice is to review) • may optionally assent to elevation by reaching consensus in a meeting within the two-
week Last Call (recommended practice is to consent but no formal Board approval vote is required)
o NOTE: When the board objects to the elevation, the board shall identify their objections and provide the Project Proponent with guidance as to what would satisfy the objection. Once the Project Proponent believes the objections have been satisfied, he/she will again request a Specification Action.
4.3 Second Maturity Level: Proposed AMWA Specifications
4.3.1 About Proposed AMWA Specifications
Proposed AMWA Specifications have the following characteristics: • The item has value to the community and provides significant benefit to industry • The item does not have known technical issues. • The item is stable, consisting of relatively complete statements or code. • Design choices have been resolved. • The item is well understood by its creators and is written or commented to support
comprehensibility by others. • The community of interest for this item has been notified of its existence and provided
with an opportunity for initial review. • The proponents believe that implementations will be developed.
Note well: Proposed specifications may change or may be retracted. Proposed specifications are published for comment, and the original committee, or the AMWA Board may decide to take appropriate action based upon comments, or upon other issues that may be discovered during initial implementation of a proposed specification. Also note that there is no requirement that any given Proposed Specification advance to the Specification level – in fact, many important AMWA documents may remain Proposed Specifications indefinitely.
4.3.2 Informative and Experimental Specifications
Informative Specifications and Experimental Specifications do not advance beyond the second maturity level.
4.3.3 Prerequisites for Proposed AMWA Specifications
Proposed AMWA Specifications: • Must be part of an approved AMWA project. • Must have a declared IPR mode as part of the approved project description (acceptable
options are RAND or RAND-Z). • Fall in the categories IS, MS, AS, or BCP, as defined in section 3 above, or are
Informative or Experimental. • Have the characteristics outlined in section 4.3.1 above. • Have successfully completed the elevation actions outlined in section 4.2.3 above.
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 10
AMWA specifications must carry specified copyright notices and licenses. See section 6.3 for details.
Some Proposed Specifications may be created in GitHub or another code repository approved by AMWA Board. Typically these will include application source code, and/or interface or data definitions that are written in a machine- and human-readable form (e.g. XML, JSON, RAML, RDF). Cross-referencing must be provided for such Proposed Specifications. In the AMWA specification, cross-reference by providing the number for the code repository version and appropriate URL identifier. In the code repository expression of the specification, cross-reference by providing the identifier and URL information for the corresponding AMWA specification. See appendix B.
4.3.4 Elevation to the Next Maturity Level: from Proposed to AMWA Specification
4.3.4.1 Elevation Actions: Project Proponent
Project proponent notifies the AMWA Operations Manager via written request that a given Proposed AMWA Specification has met elevation criteria. The written request includes:
• Identification of the item type, i.e., IS, AS, BCP, etc. • Confirms that there is no change in the title or identifier from the Proposed AMWA
Specification • Written description of how the current Proposed AMWA Specifications meets the
prerequisites for outlined in section 4.3.2 below, i.e., the written report responds to the following questions:
o What significant implementations of this specification exist at this time? o Are there examples of successful interoperation between different
implementations of this specification? Please describe. o Is there a certification authority and certification criteria for this specification? If
so, provide information indicating whether a certification process has been initiated and about the status of that process for this item.
o If there is no formal certification process, are there other relevant interoperability testing protocols, formal or informal? If so, provide information about any interoperability testing of this item.
o Are one or more licenses required to implement the specification? If so, please describe at least two different implementations that have been developed under separate licenses issued by the relevant IPR holder(s).
o How does this specification represent a high degree of technical maturity? o How does this specification provide a significant benefit to industry? o Does this specification include application source code, and/or interface or data
definitions that are written in a machine- and human-readable form (e.g. XML, JSON, RAML, RDF), being created in GitHub or other code repository approved by AMWA Board? If so, describe and/or provide URLs or other identifiers for appropriate elements in the code repository. See also appendix B.
4.3.4.2 Elevation Actions: AMWA Operations Manager
AMWA Operations Manager: • Verifies that the Proposed AMWA Specification has been approved for at least six
months
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 11
• Issues Last Call (not less than two-week notice) • Ensures IPR process has been followed • Supports the board in selection of an editor to review the specification on behalf of the
AMWA, and monitors the editor's progress in this task • After approval by the board, adjusts the AMWA identifier (deletes "Proposed"), retains
title. Example: IS-02. Restful API for MXF Versioning to support AS-02, version 1.2.
4.3.4.3 Elevation Actions: AMWA Board The AMWA Board:
• Reviews materials from the proponent and the AMWA Operations Manager • Votes on the proposed elevation; elevation to the third maturity level of AMWA
Specification requires a formal AMWA Board vote o NOTE: In the case where the board fails to approve the elevation, the board shall
identify their objections and provide the Project Proponent with guidance as to what would satisfy the objection. Once the Project Proponent believes the objections have been satisfied, he/she will again request a Specification Action.
4.4 Third Maturity Level: AMWA Specifications
4.4.1 About AMWA Specifications
AMWA Specifications have the following characteristics: • The item has value to the community and provides significant benefit to industry • The item does not have known technical issues. • The item is stable, consisting of complete statements or code. • Design choices have been resolved. • The item is well understood by its creators and is written or commented to support
comprehensibility by others. • The community of interest for this item is aware of its existence and, when posted as a
Proposed AMWA Specification, has been provided with an opportunity for review
4.4.2 Prerequisites for AMWA Specifications:
Proposed AMWA Specifications: • Must be part of an approved AMWA project. • Must have a declared IPR mode as part of the approved project description (acceptable
options are RAND or RAND-Z). • Fall in the categories IS, MS, AS, or BCP, as defined in section 3 above • Have the characteristics outlined in section 4.4.1 above. • Have significant implementations in existence • Have seen successful operational experience • Represent a high degree of technical maturity • Must have been a Proposed AMWA Specification for at least 6 months • Have successfully completed the elevation actions outlined in section 4.3.4 above.
AMWA specifications must carry specified copyright notices and licenses. See section 6.3 for details.
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 12
Some Specifications may be created in GitHub or another code repository approved by AMWA Board. Typically these will include application source code, and/or interface or data definitions that are written in a machine- and human-readable form (e.g. XML, JSON, RAML, RDF). Cross-referencing must be provided for such Specifications: (a) in the AMWA specification, provide the number for the code repository version and appropriate URL information and (b) in the code repository expression of the specification, provide identifying and URL information about the corresponding AMWA specification. See appendix B.
4.5 Revising an AMWA Specification A new version of a Specification must move through the process as if it were a completely new specification. Once the new version has reached the AMWA Specification maturity level, it will usually replace the previous version, which will be moved to Historical status. However, in some cases both versions may remain as AMWA Specifications to honor the requirements of an installed base. In this situation, the relationship between the previous and the new versions must be explicitly stated in the text of the new version or in another appropriate document.
4.6 Retiring an AMWA Specification Historical Specifications are specifications that have been superseded; they remain available, and are properly labeled to indicate that they are not current, and they reference the current version as appropriate.
As technology changes and matures, it is possible for a new specification to be so clearly superior in technical terms that one or more existing specifications for the same function should be retired. In this case, or when it is felt for some other reason that an existing specification should be retired, the AMWA Board shall approve a change of status of the old specification(s) to Historical. This recommendation shall be issued with the same Last-Call and notification procedures used for any other specification-approval action. A request to retire an existing specification can originate from a Working Group, the AMWA Board or some other interested party.
5 CONFLICT RESOLUTION AND APPEALS
5.1 Disputes Within a Working Group Disputes are possible at various stages during the AMWA specification process. The process is designed to maximize the opportunities for compromise and the achievement of genuine consensus. However, there are times when even the most reasonable and knowledgeable people are unable to agree. To achieve the goals of openness and fairness, such conflicts must be resolved by a process of open review and discussion.
An individual (whether a participant in the relevant Working Group or not) may disagree with a Working Group recommendation based on his or her belief that either (a) his or her own views have not been adequately considered by the Working Group, or (b) the Working Group has made an incorrect technical choice which places the quality and/or integrity of the Working Group's product(s) in significant jeopardy. The first issue is a difficulty with Working Group process; the latter is an assertion of technical error. Although these two types of disagreement are quite different, both are handled by the same review process.
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 13
A person who disagrees with a Working Group recommendation shall always first discuss the matter with the Working Group's chair(s), who may involve other members of the Working Group (or the Working Group as a whole) in the discussion. In cases where the Working Group chair is not the project owner, the person may subsequently bring up the issue with the project owner. The following section specifies the procedures that shall be followed to respond to AMWA specification-development issues that cannot be resolved through the actions of the AMWA Working Group that is developing the specification.
5.2 Appeal to the AMWA Board If the Working Group cannot resolve the disagreement, any of the parties involved may bring it to the AMWA Board, whose decision is final. The AMWA Executive Director shall acknowledge the receipt of such a request for Board review within two weeks, and shall at the time of acknowledgment advise the petitioner of the expected duration of the Board's consideration.
The Board shall review the situation in a manner of its own choosing and report to the petitioner and to the AMWA Working Group on the outcome of its review. The Board's decision upon completion of their review shall be final with respect to all aspects of the dispute.
5.3 Appeals Procedure All appeals made under the provisions of this section must include a detailed and specific description of the facts of the dispute. Appeals must be initiated within two months of the public knowledge of the action or decision to be challenged.
At all stages of the appeals process, the individuals or bodies responsible for making the decisions have the discretion to define the specific procedures they will follow in the process of making their decision. In all cases a decision concerning the disposition of the dispute, and the communication of that decision to the parties involved, must be accomplished within a reasonable period of time.
NOTE: These procedures intentionally and explicitly do not establish a fixed maximum time period that shall be considered "reasonable" in all cases. While there may be times that consensus is key, there may be other times when business or other considerations require quick action. Ultimately, the AMWA Board is responsible for determining the appropriate amount of time required to resolve issues brought to its attention.
6 INTELLECTUAL PROPERTY
6.1 Introductory Note on AMWA Publication and IPR Policy In order promote maximal interoperation of equipment, applications, and systems, the AMWA seeks the widest possible adoption of its specifications. At the same time, the AMWA seeks to protect patents and other intellectual property held by the companies and other organizations that comprise the media community. These two goals are supported by the AMWA’s Intellectual Property Policy.
The authoritative statement of the policy is provided in the first document listed below. The second document provides additional explanatory information. All AMWA members are encouraged to read both of these documents.
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 14
• Advanced Media Workflow Association Intellectual Property Rights Policy: http://www.amwa.tv/about/policies/AMWA_IPR_Policy_V3.0.pdf
• Advanced Media Workflow Association IPR Policy: Frequently Asked Questions: http://www.amwa.tv/about/policies/AMWA_IPR_Policy_FAQ_V3.0.pdf
6.2 Copyright and Licensing of AMWA Specifications
6.2.1 Dissemination of specifications at no cost
All AMWA Specifications, at all levels of maturity, are disseminated at no cost to all interested parties (not limited to AMWA members).
6.2.2 Specifications carry AMWA copyright notice
Each specification shall carry a copyright notice that takes this form: (c) AMWA [year-of-publication].
6.2.3 Specifications carry Creative Commons CC BY-SA license
AMWA specifications shall carry the Creative Commons license "CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)" in addition to the copyright notice specified in 6.3.2. This license allows others to copy and redistribute the material in any medium or format; remix, transform, and build upon the material for any purpose, even commercially. However, if the user remixes, transforms, or builds upon the material, the new contributions must be distributed under the same license as the original. Re-users must give appropriate credit, provide a link to the license, and indicate if changes were made. This may be done in any reasonable manner, but not in any way that suggests the licensor endorses the new use. See http://creativecommons.org/licenses/by-sa/4.0/.
The following Creative Commons statement shall be carried near the location in the specification where the copyright notice is printed:
• Creative Commons license: "CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)." See http://creativecommons.org/licenses/by-sa/4.0/.
6.3.4 Specifications in the form of software carry the Apache 2.0 license
AMWA Specifications in the form of software applications shall carry the Apache 2.0 license, using the following or an equivalent statement embedded as comments in the application's code:
• (c) AMWA [year-of-publication] • Licensed under the Apache License, Version 2.0 (the "License"); you may not use this
file except in compliance with the License. You may obtain a copy of the License at • http://www.apache.org/licenses/LICENSE-2.0 • Unless required by applicable law or agreed to in writing, software distributed under the
License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
• See the License for the specific language governing permissions and limitations under the License.
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 15
Appendix A. Inclusion of Identifiers, Titles, and References Note: Most of the URLs in this appendix are hypothetical, illustrative examples, and they will not actually resolve.
A.1 AMWA specification relationships to other documents or data In order to orient and inform users, AMWA specifications must provide information about:
• The specification's identity and status within the AMWA process, as specified in A.2 below.
• If applicable, the specification's relationship to the work and processes of cooperating organizations, as specified in A.3 below.
• If applicable, the location of code or other elements essential to the AMWA specification that are maintained within the GitHub repository (or other code repository approved by the AMWA Board), as specified in A.4 below.
A.2 AMWA identifier, title, and other data in specification header
The data types listed in the bullets below shall be presented in the AMWA specification's header. An illustrative example is provided in A.2.1 below.
• AMWA specification identifier: o If the specification is a WIP, no AMWA specification identifier has yet been
assigned, and the identifier data element is left blank (or null value). o If the specification is at the proposed or approved-specification level, then the
header should carry the AMWA specification identifier, e.g., BCP-74, as assigned by the AMWA Operations Manager when the specification moves from the status of WIP to that of Proposed Specification.
• AMWA title, e.g., Finished Content Delivery – MXF for HD LongGOP Programs (Non-Integer Framerates).
• Related facts, e.g, AMWA maturity status, date of publication, and the URL for the location on the AMWA website.
Once assigned, the AMWA identifiers are immutable. Any revisions ("next versions") will be assigned a new AMWA identifier. In a prose document, the header will look more or less like the illustrative example that follows. In non-prose specifications, the header may take an appropriate form (e.g., XML, JSON, RAML, etc.) or the header may be inserted as a labeled and tag-carrying block of ASCII text.
A.2.1 Illustrative example of a header
AMWA ID: BCP-074 AMWA title: Finished Content Delivery – MXF for HD LongGOP Programs (Non-Integer Framerates) Type: Best Current Practice (BCP) Project leader: Thomas Heritage, BBC Maturity level: AMWA Specification Date published: 31 July 2016
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 16
Location: http://www.amwa.tv/projects/BCP-74.shtml Comment: Created in GitHub as set of blocks
A.3 Other organization identifier and title in specification scope statement When applicable, information about other organizations involved in the development or use of this specification shall be included in the AMWA specification's scope statement. The types of information include other organization's identifier (if any, with an indication of that identifier's type and value), title, and other data.
A.3.1 Illustrative example of other organization information in scope statement
Other organization name: Digital Production Partnership Ltd. Other org title: Finished Content Delivery – MXF for HD LongGOP Programs (Non-Integer
Framerates) Other org ID: AS-11 X4 Other org ID type: DPP identifier Other org ID location: https://www.digitalproductionpartnership.co.uk/spe
A.4 References to GitHub or other code repository where relevant This section pertains to AMWA specifications that include code elements and other components, developed and maintained in GitHub (or other repository), by reference.
A.4.1 Reference to the overall project in GitHub or other repository
The overall GitHub (or other repository) project shall be identified and referenced in the AMWA specification scope statement. The description shall provide the name, URL and tag(s) within the repository that represent that repository's "immutable" version, and any other relevant whole-project information (e.g., version number) maintained within the code repository.
A.4.2 Illustrative examples of overall GitHub project reference
The following is an example of a reference to an overall GitHub project, to be incorporated in the AMWA specification scope statement. If a different code repository (approved by the AMWA Board) is used, a similar information block shall be incorporated in the scope statement. GitHub project name: Finished Content Delivery – MXF for HD LongGOP Programs (Non-
Integer Framerates) GitHub project (general) location: https://github.com/AMWA-TV/xyz123 GitHub project version: v. 3 GitHub project (version) location: https://github.com/AMWA-TV/xyz123/abc789
A.4.3 Reference to project segments or "blocks" in GitHub or other code repository
In some cases, GitHub (or other repository approved by the AMWA Board) may serve as the repository for a set of "blocks" (component parts of a specification). Selected members of the set are incorporated in a given AMWA specification. In such cases, links to URL and tag(s) within the repository that represent that repository's "immutable" version for a given block shall be interspersed in the AMWA version of the specification as needed.
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 17
A.4.4 Illustrative examples of GitHub reference to a "block"
This subsection of the appendix presents two examples of references to GitHub "blocks" (code or other segment), to be incorporated in the AMWA specification where the code or other element belongs on the specification sequence. If a different code repository (approved by the AMWA Board) is used, a similar information block shall be incorporated where needed. GitHub block location: www.amwa.tv/rulesv2/block/345
GitHub block version: v. 3
GitHub block location: www.amwa.tv/rulesv2/block/487 GitHub block version: v. 9
A.5 Other illustrative examples
A.5.1 Work in progress example
Header AMWA ID: null [not yet assigned] AMWA title: Restful API for MXF Versioning to support AS-02, version 1.2 Type: Interface Specification (IS) Project leader: Richard Cartwright Maturity level: AMWA WIP Date published: 31 July 2016 Location: http://www.amwa.tv/projects/WIP2.shtml Comment: Created in GitHub as unified specification
Scope statement to include
Other ID: [not applicable; can be omitted] GitHub project name: Restful API for MXF Versioning GitHub project (general) location: https://github.com/AMWA-TV/wip2 GitHub project version: v. 8 GitHub project (version) location: https://github.com/AMWA-TV/wip2/xyz123
In specification where needed
GitHub block location: [not applicable; can be omitted]
A.5.2 Proposed Specification example
Header AMWA ID: MS-014 (Proposed) AMWA title: Data Model for AAF-2, version 2.3 Type: Data Model Specification (MS) Project leader: Donald Clinton Maturity level: Proposed AMWA Specification Date published: 19 September 2019 Location: http://www.amwa.tv/projects/AAF2_2_3
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 18
Comment: Created in GitHub as unified specification Scope statement to include
Other ID: [not applicable; can be omitted] GitHub project name: Data Model for AAF-2 GitHub project (general) location: https://github.com/AMWA-TV/wip6 GitHub project version: v. 12 GitHub project (version) location: https://github.com/AMWA-TV/wip6/mno476
In specification where needed
GitHub block location: [not applicable; can be omitted]
A.5.3 Approved Specification example
Header AMWA ID: BCP-074 AMWA title: Finished Content Delivery – MXF for HD LongGOP Programs (Non-Integer
Framerates) Type: Best Current Practice (BCP) Project leader: Richard Cartwright Maturity level: AMWA Specification Date published: 14 August 2017 Location: http://www.amwa.tv/projects/BCP-74.shtml Comment: Created in GitHub as set of blocks
Scope statement to include
Other ID: AS-11 X4 Other ID type: DPP identifier (adaptation of former AMWA ID type) Other ID location: https://www.digitalproductionpartnership.co.uk/spe Other ID responsible party: Digital Production Partnership Ltd. Other ID comment: (none)
GitHub project relationship GitHub project (general) location: https://github.com/AMWA-TV/xyz123 GitHub project version: v. 6 GitHub project (version) location: https://github.com/AMWA-TV/xyz123/abc789
In specification where needed
GitHub block location: www.amwa.tv/rulesv2/block/345 GitHub block version: v. 1
GitHub block location: www.amwa.tv/rulesv2/block/487
GitHub block version: v. 5
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 19
Appendix B. How projects developed in a code repository relate to the AMWA specification process
B.1 Specifications created in GitHub or other code repositories may be represented at AMWA's website AMWA specifications increasingly take machine-readable form and feature application source code, and/or interface or data definitions that are written in a machine- and human-readable form (e.g. XML, JSON, RAML, RDF). Thus many AMWA working groups have begun to develop and maintain specifications in a code repository hosting service. This appendix outlines the relationship between the entities developed and maintained in such code repositories and the AMWA Specification process outlined in the main part of this document.
At the time of the initial adoption of this process document by the AMWA Board, GitHub is the repository that has been approved for specification development. The examples given are stated in terms of GitHub practices. In the future, however, the AMWA Board may approve additional code repositories for this type of development, and the process requirements in this document shall be understood to apply to those additional repositories. If the practices between GitHub and any additional repository are significantly different, an additional appendix will be drafted and approved by the AMWA Board to provide needed guidance.
At a high level, the relationship is this:
• The entirety or blocks of a specification (see B.2 below) for an AMWA-approved project are brought to state of readiness in GitHub or other repository. This version of the specification or the block(s) is/are "frozen" within the repository, using that repository's methods to lock and identify it/them.
• An AMWA document or web page (see B.6 below) that reference the repository's resources are prepared, and introduced as an AMWA Work in Progress (WIP).
• The copy of the specification presented in the AMWA context may move through as much of the entire AMWA process as the project owner wishes, following the outline in the main part of this document.
• Meanwhile, development and evolution of the underlying specification elements in the repository may continue, beyond the "frozen" version. When a new version exists in the repository that is appropriate for AMWA consideration, it can be introduced in the AMWA process, where it will proceed as a new and distinct specification.
B.2 Entities in code repositories: full specifications and blocks AMWA working groups may create a unified and whole specification in the code repository, or they may create separate segments or component parts of the specification, called blocks. Selected blocks may subsequently be assembled to create instances of a full specification.
The term block for a component of a specification comes from the DPP implementation of AS-11, in which various DPP subgroups create specifications that are variants of AS-11 by assembling multiple blocks (in this case, managed in GitHub). The specification represented by the selected blocks may extend or constrain a given specification when compared to its sibling.
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 20
This approach differs from the traditional AMWA shim, which permits only the application of constraints defined in the main (complete) specification. The DPP variant versions of AS-11 may or may not interoperate.
B.3 Versions "frozen" in the code repository From time to time, the development process in a code repository yields numbered-and-approved versions, sometimes referred to as milestone versions of a specification or a block, and these are identified or "tagged" in the repository by a unique URL and version numbers, e.g., v1.2, v1.3, etc. Freezing means that the item will be more stable for implementers, although they should understand that evolution may continue in the repository, with new versions that will have an incremented version number and a new URL.
B.4 Handoff from the code repository to AMWA The owner of a specification being constructed via a code repository chooses to submit a milestone version to the AMWA Specification process as a Work in Progress. When an item is elevated to the level of Proposed Specification, it will be assigned an AMWA identifier. This stabilizes the version at AMWA, although as comments are received, the project's working group may make adjustments and correct errors.
In order to graduate to the maturity level of AMWA Approved Specification, the item is required to have been presented as an AMWA Proposed Specification for at least six months, and meet the other requirements listed in the main AMWA process document.
B.5 Scope statements in the code repository and in the AMWA expression of the specification Specialists in the field recommend that application creators include a prose introduction as a part of their code repository resource for a given project. The AMWA expression of the specification should carry a prose statement that is an elaboration of the prose statement at the repository. The elaborated AMWA prose note should emphasize the specification's business value, rather than merely repeating technical information.
B.6 Formatting options for AMWA specifications with code repository components The AMWA expression of a specification will not include the actual code or other components maintained in the code repository. These components will be incorporated by reference. That is, the AMWA online specification document should carry one or more URL pointer or pointers to the code location(s) at the repository.
The AMWA does not have a set requirement for the formatting of the AMWA expression of a specification that components located in a repository. Two approaches are outlined below. Creators of specifications may adopt one of these approaches, find ways to combine the two, or propose approaches that have the same outcome in terms of providing needed information.
Option 1. Prose statement with links. In this approach, the AMWA document consists of a prose statement containing at minimum a scope note. This scope note should include a set of appropriately labeled URL links to the resource(s) in the code repository. When the repository resource consists of blocks, as described in B.2 above, the scope note should contain links to the
AMWA BCP-001 - (c) AMWA 2016, CC Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) Page 21
main or overall representation in that repository. Subsequent sections of the AMWA expression of the specification should then include explanatory statements that, in turn, link to blocks in the repository.
Option 2. HTML framework at the AMWA website, with section by section links to the relevant repository materials presented as actionable URLs in the HTML structure. The HTML serves as a framework for the specification, often section by section, with hyperlinks that bring up (a) code or other block-based resources in the code repository and (b) additional (local, often relative links to the same directory that hold the main HTML framework file) informative and explanatory statements. This HTML framework option provides good support for a specification when the resource in the repository consists of blocks.
B.7 Reference to the AMWA expression of the specification at the code repository Explanatory or scope statements about a project that are provided at the code repository website should state the relationship of the repository resource to the AMWA expression of the specification. This statement of relationship should include such elements as the AMWA URL, identifier, and title.
In addition, especially for cases in which the code repository resource includes blocks or segments of the AMWA specification, additional referencing and/or prose statements about the relationship should be provided at appropriate locations in the repository resource.