Clarify when VCF meta entries are mandatory

[cyenyxe]

The specifications states the following:

It is strongly encouraged that information lines describing the INFO, FILTER and FORMAT entries used in the body of the VCF file be included in the meta-information section. Although they are optional, if these lines are present then they must be completely well-formed.

But vcftools at least creates an error when they are not present. I found it in the code (http://sourceforge.net/p/vcftools/code/HEAD/tree/trunk/perl/Vcf.pm#l2366), not from the console output. What would be the preferred behaviour?

For ALT metadata describing alleles such as <DEL> or <INS>, nothing is stated and vcftools doesn't raise an error if they are not described. Should I assume these are optional too? Anyway, if some are mandatory but others don't it would be interesting to highlight this difference.

[eitanbanks]

My vote is that they be treated just like any other header lines: they are optional but if present must be well-formed.
Note that tools may still choose to require them (and will exit with a friendly error saying "sorry, but we won't process your VCF until it has them included"). But the spec doesn't need to enforce that.

[pd3]

@eitanbanks +1 from me.

However, to make it clear that we do not encourage undefined tags, I included the following sentence in the draft:

Note that BCF, the binary counterpart of VCF, requires that all entries are
present, therefore the use of undefined tags is strongly discouraged.

[cyenyxe]

Thank you both for your answers, I agree with the "optional but well-formed if present" idea. The BCF note is also adequate, but I still find the previous paragraph confusing.

If I can make a suggestion, I would write something like the following. The order is somewhat changed to refer first to meta-information lines in general, then recommendations for specific tags.

File meta-information is included after the ## string and must be key=value
pairs. Meta-information lines are optional, but if they are present then
they must be completely well-formed {\color{red} and their ID must be
unique within their type. Note that BCF, the binary counterpart of VCF, requires
that all entries are present.

It is strongly encouraged to include meta-information lines describing the \texttt{INFO},
\texttt{FILTER}, \texttt{FORMAT} and {\color{red}\texttt{contig}} entries used
in the body of the VCF file.

Meta-information lines can be in any order with the exception of fileformat
which must come first.

Please let me know your opinions, and if I should make a PR for this.

[pd3]

I think that reads better, thank you. There was a proposal discussed at length offline to make the ID attribute mandatory for all structured values. With this addition, the section would read like this:

File meta-information is included after the ## string and must be key=value
pairs. Meta-information lines are optional, but if they are present then
they must be completely well-formed. {\color{red} Note that BCF, the binary
counterpart of VCF, requires that all entries are present. It is strongly
encouraged to include meta-information lines describing the entries used in the
body of the VCF file.

All structured lines that have their value enclosed within "$<>$" require an ID
which must be unique within their type.

Meta-information lines can be in any order with the exception of fileformat
which must come first.}

[cyenyxe]

Looks good to me :)

[pd3]

Since there were no further comments, I am closing the issue as solved.