Add variant to file references.

Contest_API.md

@@ -264,14 +264,15 @@ Properties for geographic location objects:
 
 Properties for file reference objects:
 
-| Name     | Type      | Description
-| -------- | --------- | -----------
-| href     | string    | URL where the resource can be found. Relative URLs are relative to the `baseurl`. Must point to a file of intended mime-type. Resource must be accessible using the exact same (possibly none) authentication as the call that returned this data. (Note: this is actually optional inside a [Contest Package](contest_package)).
-| filename | string    | POSIX compliant filename. Filenames must be unique within the endpoint object where they are used. I.e. an organization can have (multiple) `logo` and `country_flag` file references, they must all have a different filename, but different organizations may have files with the same filename.
-| hash     | string ?  | MD5 hash of the file referenced.
-| mime     | string    | Mime type of resource.
-| width    | integer ? | Width of the image. Required for files with mime type image/\*.
-| height   | integer ? | Height of the image. Required for files with mime type image/\*.
+| Name     | Type            | Description
+| -------- | --------------- | -----------
+| href     | string          | URL where the resource can be found. Relative URLs are relative to the `baseurl`. Must point to a file of intended mime-type. Resource must be accessible using the exact same (possibly none) authentication as the call that returned this data. (Note: this is actually optional inside a [Contest Package](contest_package)).
+| filename | string          | POSIX compliant filename. Filenames must be unique within the endpoint object where they are used. I.e. an organization can have (multiple) `logo` and `country_flag` file references, they must all have a different filename, but different organizations may have files with the same filename.
+| hash     | string ?        | MD5 hash of the file referenced.
+| mime     | string          | Mime type of resource.
+| width    | integer ?       | Width of the image. Required for files with mime type image/\*.
+| height   | integer ?       | Height of the image. Required for files with mime type image/\*.
+| variant  | array of string | Intended usage hints (e.g. `light`, `dark` for images).
 
 The `href` property may be an [absolute or relative
 URL](https://datatracker.ietf.org/doc/html/rfc3986); relative URLs must be
@@ -292,6 +293,13 @@ the values of `width` and `height` should be the viewport width and height in pi
 when possible, but otherwise the actual values don't matter as long as they
 are positive and represent the correct aspect ratio.
 
+Known values of variant include:
+
+- `light`: an image intended for use on white or light backgrounds.
+- `dark`: an image intended for use on black or dark backgrounds.
+
+An image may list both values if it is suitable for multiple contexts.
+
 If implementing support for uploading files pointed to by resource
 links, substitute the href property with a data property with a base64
 encoded string of the associated file contents as the value.

Contest_Package.md

@@ -73,12 +73,11 @@ filename pattern must be loaded in addition to any file references
 found in the json files.
 
 The default filename pattern is
-`<endpoint>/<id>/<property>(.variant).<extension>`, where:
+`<endpoint>/<id>/<property>(.<variant>)*.<extension>`, where:
 
 - `<id>` is the ID of the endpoint object the reference is in.
 - `<property>` is the property of the object, e.g. `logo`.
-- `(.<variant>)` is an optional variant. Must be used when there are
-  multiple files to avoid collisions.
+- `(.<variant>)*` is one or several optional variant tags.
 - `<extension>` is a file extension corresponding to the mime type.
 
 For images, the supported file extensions are:
@@ -89,8 +88,10 @@ For images, the supported file extensions are:
 | image/jpeg    | jpg, jpeg
 | image/svg+xml | svg
 
-For images, the variant should be `.<W>x<H>`, where W and H are the width and
-height of the image in pixels, e.g. logo.56x54.png.
+For images, a variant of `.<W>x<H>`, is interpreted as the file reference object
+having the `width` property set to  `<W>` and the `height` property set to
+`<H>`. Every other variant is interpreted as the file reference object having
+the value its `variant` property array.
 
 #### Hrefs