diff --git a/README.md b/README.md
index 25ec9290c..a2aa4f13c 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,47 @@ generate the `.yaml` entries here.
 
 ## Using this data
 
+### Marking specific attributes
+It can be helpful to know which specific code elements of a package are vulnerable and this is done by appending an attribute and list of module paths starting from the top level module of a package to the OSV payload. Eg. 
+OSV entries in this database have the following ecosystem_specific definition: 
+```json
+"ecosystem_specific": {
+  "imports": [
+    { 
+       "attribute": string,
+       "modules": [ string ],
+    }
+  ]
+}
+```
+"imports" is a JSON array containing the modules and attributes affected by the vulnerability...
+For example, a vulnerability that affects PIL::ImageFont can be represented as...
+```json
+"imports": [
+  {
+    "attribute": "ImageFont",
+    "modules": ["PIL"]
+  }
+]
+```
+which is equivalent to `PIL:ImageFont`. If a second attribute `ImageFont2` is also affected, then a second import entry needs to be added to the `imports` array. 
+```json
+"imports": [
+  { "attribute": "ImageFont", "modules": ["PIL"] },
+  { "attribute": "ImageFont2", "modules": ["PIL"] }
+]
+```
+
+Attributes which are accessible via multiple paths may be represented in a condensed form. Consider the attribute `django.db.models:JSONField` from the [django project](https://github.com/django/django/blob/0ee2b8c326d47387bacb713a3ab369fa9a7a22ee/django/db/models/__init__.py#L99) 
+The attribute `django.db.models:JSONField` is a re-export of `django.db.models.fields.json:JSONField` and both are valid paths.
+These can be condensed to a more compact OSV representation as 
+```
+{
+  attribute: "JSONField",
+  modules: ["django.db.models", "django.db.models.fields.json"]
+}
+```
+
 ### Tooling
 
 This data is exposed by [`pip-audit`](https://github.com/pypa/pip-audit),